Skip to main content

ydp_core/
runtime.rs

1use crate::raw::{ByteBudget, Frame, FrameText};
2use crate::*;
3use bytes::Bytes;
4use futures_core::{Stream, future::FusedFuture};
5use futures_util::task::AtomicWaker;
6use pin_project_lite::pin_project;
7use std::{
8    collections::{BTreeMap, BTreeSet, VecDeque},
9    future::Future,
10    io,
11    marker::PhantomData,
12    pin::Pin,
13    sync::{
14        Arc, Mutex, MutexGuard, Weak,
15        atomic::{AtomicU64, Ordering},
16    },
17    task::{Context, Poll, Waker},
18    time::Duration,
19};
20use tokio::sync::{Notify, oneshot};
21use tokio::time::{Instant, Sleep};
22
23fn lock<T>(value: &Mutex<T>) -> MutexGuard<'_, T> {
24    match value.lock() {
25        Ok(g) => g,
26        Err(p) => p.into_inner(),
27    }
28}
29fn wake(wakers: Vec<Waker>) {
30    for w in wakers {
31        w.wake();
32    }
33}
34static NEXT_CONNECTION: AtomicU64 = AtomicU64::new(1);
35struct Route {
36    key: SessionKey,
37    id: Option<SessionId>,
38}
39struct ApiLease {
40    shared: Arc<Shared>,
41}
42impl Drop for ApiLease {
43    fn drop(&mut self) {
44        self.shared
45            .begin_close(Error::new(ErrorKind::ConnectionClosed));
46    }
47}
48struct Shared {
49    key: ConnectionKey,
50    control: Mutex<Control>,
51    outbox: Notify,
52    stop: Notify,
53    closed: Notify,
54    options: RuntimeOptions,
55    wire_budget: Arc<ByteBudget>,
56    #[cfg(test)]
57    task: Mutex<Option<tokio::task::JoinHandle<()>>>,
58}
59struct Control {
60    state: ConnectionState,
61    reason: Option<Error>,
62    close_started: Option<Instant>,
63    report: Option<CloseReport>,
64    supplemental_errors: Vec<Error>,
65    supplemental_seen: [bool; 2],
66    pending: BTreeMap<i32, Pending>,
67    queues: [VecDeque<Outbound>; 2],
68    counts: [Counts; 2],
69    waiters: BTreeMap<u64, Waiter>,
70    fifo: [VecDeque<u64>; 2],
71    next_waiter: u64,
72    next_request: i64,
73    routes: BTreeMap<SessionId, Arc<Route>>,
74    retired: std::collections::BTreeSet<SessionId>,
75    next_session: u64,
76    subscriptions: BTreeMap<u64, Arc<Subscriber>>,
77    all: BTreeSet<u64>,
78    wild: BTreeMap<SessionKey, BTreeSet<u64>>,
79    exact: BTreeMap<SessionKey, BTreeMap<&'static str, BTreeSet<u64>>>,
80    active_keys: BTreeSet<SessionKey>,
81    subscription_count: usize,
82    next_subscription: u64,
83    seq: u64,
84    control_streak: usize,
85    closed_pending: usize,
86    closed_outbound: usize,
87}
88impl Control {
89    fn remove_subscription(&mut self, id: u64) -> Option<Arc<Subscriber>> {
90        let subscriber = self.subscriptions.remove(&id)?;
91        match subscriber.route {
92            None => {
93                self.all.remove(&id);
94            }
95            Some(key) => {
96                if let Some(method) = subscriber.method {
97                    if let Some(methods) = self.exact.get_mut(&key) {
98                        if let Some(ids) = methods.get_mut(method) {
99                            ids.remove(&id);
100                            if ids.is_empty() {
101                                methods.remove(method);
102                            }
103                        }
104                        if methods.is_empty() {
105                            self.exact.remove(&key);
106                        }
107                    }
108                } else if let Some(ids) = self.wild.get_mut(&key) {
109                    ids.remove(&id);
110                    if ids.is_empty() {
111                        self.wild.remove(&key);
112                    }
113                }
114            }
115        }
116        Some(subscriber)
117    }
118}
119#[derive(Default)]
120struct Counts {
121    requests: usize,
122    slots: usize,
123    bytes: usize,
124    waiters: usize,
125}
126struct Waiter {
127    route: SessionKey,
128    class: usize,
129    granted: bool,
130    waker: Option<Waker>,
131}
132struct Pending {
133    route: Arc<Route>,
134    sender: oneshot::Sender<Delivery>,
135    permit: Permit,
136}
137struct Delivery {
138    result: Result<RawReply>,
139    _permit: Permit,
140}
141struct Outbound {
142    bytes: Bytes,
143    _permit: Permit,
144}
145#[derive(Clone, Copy)]
146enum PermitKind {
147    Request,
148    Outbound,
149}
150struct Permit {
151    shared: Weak<Shared>,
152    class: usize,
153    kind: PermitKind,
154    bytes: usize,
155}
156impl Drop for Permit {
157    fn drop(&mut self) {
158        if let Some(s) = self.shared.upgrade() {
159            let ws = {
160                let mut c = s.control();
161                match self.kind {
162                    PermitKind::Request => c.counts[self.class].requests -= 1,
163                    PermitKind::Outbound => {
164                        c.counts[self.class].slots -= 1;
165                        c.counts[self.class].bytes -= self.bytes;
166                    }
167                }
168                s.grant(&mut c)
169            };
170            wake(ws);
171        }
172    }
173}
174struct Guard {
175    shared: Weak<Shared>,
176    waiter: Option<u64>,
177    id: Option<i32>,
178}
179impl Drop for Guard {
180    fn drop(&mut self) {
181        if let Some(s) = self.shared.upgrade() {
182            let (removed, waker, ws) = {
183                let mut c = s.control();
184                let removed = self.id.and_then(|id| c.pending.remove(&id));
185                let mut old = None;
186                if let Some(id) = self.waiter
187                    && let Some(w) = c.waiters.remove(&id)
188                {
189                    c.counts[w.class].waiters -= 1;
190                    if w.granted {
191                        c.counts[w.class].requests -= 1;
192                        c.counts[w.class].slots -= 1;
193                    }
194                    c.fifo[w.class].retain(|v| *v != id);
195                    old = w.waker;
196                }
197                let ws = s.grant(&mut c);
198                (removed, old, ws)
199            };
200            drop(removed);
201            drop(waker);
202            wake(ws);
203        }
204    }
205}
206impl Shared {
207    fn control(&self) -> MutexGuard<'_, Control> {
208        match self.control.lock() {
209            Ok(guard) => guard,
210            Err(poisoned) => {
211                drop(poisoned.into_inner());
212                self.control.clear_poison();
213                self.begin_close(Error::new(ErrorKind::DriverFailed));
214                lock(&self.control)
215            }
216        }
217    }
218
219    fn class(&self, i: usize) -> ClassLimits {
220        if i == 0 {
221            self.options.limits.normal
222        } else {
223            self.options.limits.control
224        }
225    }
226    fn route_open(c: &Control, key: SessionKey) -> bool {
227        key.sequence == 0 || c.active_keys.contains(&key)
228    }
229    fn gate(c: &Control, key: SessionKey) -> Result<()> {
230        if c.state != ConnectionState::Open {
231            Err(Error::new(ErrorKind::ConnectionClosed))
232        } else if !Self::route_open(c, key) {
233            Err(Error::new(ErrorKind::SessionClosed))
234        } else {
235            Ok(())
236        }
237    }
238    fn grant(&self, c: &mut Control) -> Vec<Waker> {
239        let mut ws = Vec::new();
240        if c.state != ConnectionState::Open {
241            return ws;
242        }
243        for i in 0..2 {
244            let limit = self.class(i);
245            while c.counts[i].requests < limit.requests && c.counts[i].slots < limit.outbound_slots
246            {
247                let Some(id) = c.fifo[i].pop_front() else {
248                    break;
249                };
250                if let Some(w) = c.waiters.get_mut(&id) {
251                    w.granted = true;
252                    c.counts[i].requests += 1;
253                    c.counts[i].slots += 1;
254                    if let Some(w) = w.waker.take() {
255                        ws.push(w);
256                    }
257                }
258            }
259        }
260        ws
261    }
262    fn permits(self: &Arc<Self>, class: usize) -> (Permit, Permit) {
263        (
264            Permit {
265                shared: Arc::downgrade(self),
266                class,
267                kind: PermitKind::Request,
268                bytes: 0,
269            },
270            Permit {
271                shared: Arc::downgrade(self),
272                class,
273                kind: PermitKind::Outbound,
274                bytes: 0,
275            },
276        )
277    }
278    fn admission(
279        self: &Arc<Self>,
280        route: SessionKey,
281        class: usize,
282        guard: &mut Guard,
283        cx: &Context<'_>,
284    ) -> Poll<Result<(Permit, Permit)>> {
285        let incoming = cx.waker().clone();
286        let mut old = None;
287        let result = {
288            let mut c = self.control();
289            match Self::gate(&c, route) {
290                Err(e) => Poll::Ready(Err(e)),
291                Ok(()) => {
292                    if let Some(id) = guard.waiter {
293                        if c.waiters.get(&id).is_some_and(|w| w.granted) {
294                            let waiter = c.waiters.remove(&id);
295                            c.counts[class].waiters -= 1;
296                            guard.waiter = None;
297                            old = waiter.and_then(|w| w.waker);
298                            Poll::Ready(Ok(self.permits(class)))
299                        } else if let Some(w) = c.waiters.get_mut(&id) {
300                            old = w.waker.replace(incoming);
301                            Poll::Pending
302                        } else {
303                            Poll::Ready(Err(Error::new(ErrorKind::SessionClosed)))
304                        }
305                    } else {
306                        let limit = self.class(class);
307                        if c.fifo[class].is_empty()
308                            && c.counts[class].requests < limit.requests
309                            && c.counts[class].slots < limit.outbound_slots
310                        {
311                            c.counts[class].requests += 1;
312                            c.counts[class].slots += 1;
313                            Poll::Ready(Ok(self.permits(class)))
314                        } else if c.counts[class].waiters >= limit.admission_waiters {
315                            Poll::Ready(Err(Error::new(ErrorKind::AdmissionFull)))
316                        } else if let Some(id) = c.next_waiter.checked_add(1) {
317                            c.next_waiter = id;
318                            c.counts[class].waiters += 1;
319                            c.fifo[class].push_back(id);
320                            c.waiters.insert(
321                                id,
322                                Waiter {
323                                    route,
324                                    class,
325                                    granted: false,
326                                    waker: Some(incoming),
327                                },
328                            );
329                            guard.waiter = Some(id);
330                            Poll::Pending
331                        } else {
332                            Poll::Ready(Err(Error::new(ErrorKind::ResourceLimit {
333                                resource: "admission_id",
334                            })))
335                        }
336                    }
337                }
338            }
339        };
340        drop(old);
341        result
342    }
343    fn begin_close(&self, error: Error) -> bool {
344        let (pending, queues, waiters, subs) = {
345            let mut c = self.control();
346            if c.state != ConnectionState::Open {
347                return false;
348            }
349            c.state = ConnectionState::Closing;
350            c.reason = Some(error.clone());
351            c.close_started = Some(Instant::now());
352            let pending = std::mem::take(&mut c.pending);
353            let queues = std::mem::take(&mut c.queues);
354            let waiters = std::mem::take(&mut c.waiters);
355            for w in waiters.values() {
356                c.counts[w.class].waiters -= 1;
357                if w.granted {
358                    c.counts[w.class].requests -= 1;
359                    c.counts[w.class].slots -= 1;
360                }
361            }
362            c.fifo = [VecDeque::new(), VecDeque::new()];
363            c.closed_pending = pending.len();
364            c.closed_outbound = queues.iter().map(VecDeque::len).sum();
365            c.all.clear();
366            c.wild.clear();
367            c.exact.clear();
368            c.active_keys.clear();
369            let subs = std::mem::take(&mut c.subscriptions);
370            (pending, queues, waiters, subs)
371        };
372        for (_, p) in pending {
373            let _ = p.sender.send(Delivery {
374                result: Err(error.clone()),
375                _permit: p.permit,
376            });
377        }
378        drop(queues);
379        for (_, w) in waiters {
380            if let Some(w) = w.waker {
381                w.wake();
382            }
383        }
384        for (_, s) in subs {
385            s.terminate(error.clone());
386        }
387        self.stop.notify_waiters();
388        self.outbox.notify_one();
389        true
390    }
391    fn supplement(&self, direction: usize, error: Error) {
392        let mut error = Some(error);
393        {
394            let mut c = self.control();
395            if !c.supplemental_seen[direction] {
396                c.supplemental_seen[direction] = true;
397                if let Some(error) = error.take() {
398                    c.supplemental_errors.push(error);
399                }
400            }
401        }
402        drop(error);
403    }
404    fn finish(&self, end: TransportEnd) {
405        let registry = {
406            let mut c = self.control();
407            if c.state == ConnectionState::Closed {
408                return;
409            }
410            (
411                std::mem::take(&mut c.routes),
412                std::mem::take(&mut c.retired),
413            )
414        };
415        drop(registry);
416        {
417            let mut c = self.control();
418            let supplemental_errors = std::mem::take(&mut c.supplemental_errors);
419            let report = CloseReport {
420                supplemental_errors,
421                reason: c
422                    .reason
423                    .clone()
424                    .unwrap_or_else(|| Error::new(ErrorKind::DriverFailed)),
425                transport_end: end,
426                pending_count: c.closed_pending,
427                discarded_outbound: c.closed_outbound,
428                driver_resources_released: true,
429            };
430            c.state = ConnectionState::Closed;
431            c.report = Some(report);
432        }
433        self.closed.notify_waiters();
434    }
435    async fn stopped(&self) {
436        loop {
437            let n = self.stop.notified();
438            tokio::pin!(n);
439            n.as_mut().enable();
440            if self.control().state != ConnectionState::Open {
441                return;
442            }
443            n.await;
444        }
445    }
446    fn pop(&self) -> Option<Outbound> {
447        self.pop_with_budget(None)
448    }
449    fn pop_with_budget(&self, remaining: Option<usize>) -> Option<Outbound> {
450        let mut c = self.control();
451        let normal = !c.queues[0].is_empty();
452        let control = !c.queues[1].is_empty();
453        let class = if control && (!normal || c.control_streak < 8) {
454            1
455        } else if normal {
456            0
457        } else {
458            return None;
459        };
460        if remaining.is_some_and(|remaining| {
461            c.queues[class]
462                .front()
463                .is_some_and(|frame| frame.bytes.len() > remaining)
464        }) {
465            return None;
466        }
467        c.control_streak = if class == 1 {
468            (c.control_streak + 1).min(8)
469        } else {
470            0
471        };
472        c.queues[class].pop_front()
473    }
474}
475struct BudgetWriter {
476    shared: Arc<Shared>,
477    permit: Permit,
478    bytes: Vec<u8>,
479    limit: usize,
480    exceeded: bool,
481}
482impl io::Write for BudgetWriter {
483    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
484        let Some(total) = self.bytes.len().checked_add(buf.len()) else {
485            self.exceeded = true;
486            return Err(io::Error::other("编码预算耗尽"));
487        };
488        let allowed = {
489            let mut c = self.shared.control();
490            let count = &mut c.counts[self.permit.class];
491            if total > self.limit
492                || count
493                    .bytes
494                    .checked_add(buf.len())
495                    .is_none_or(|v| v > self.shared.class(self.permit.class).outbound_bytes)
496            {
497                false
498            } else {
499                count.bytes += buf.len();
500                true
501            }
502        };
503        if !allowed {
504            self.exceeded = true;
505            return Err(io::Error::other("编码预算耗尽"));
506        }
507        self.permit.bytes += buf.len();
508        self.bytes.extend_from_slice(buf);
509        Ok(buf.len())
510    }
511    fn flush(&mut self) -> io::Result<()> {
512        Ok(())
513    }
514}
515
516/// 可 Clone 的连接访问句柄;最后公开访问 lease 消失会请求退出。
517#[derive(Clone)]
518pub struct Connection {
519    lease: Arc<ApiLease>,
520    root: Arc<Route>,
521}
522impl Connection {
523    /// 接管已建立传输,同步安装初始 All 订阅,再启动唯一 Driver。
524    /// 无 Tokio Handle 返回 NoRuntime;runtime 必须启用 time,否则 Tokio 可能 panic。
525    /// ```no_run
526    /// fn create<T: ydp_core::Transport>(transport: T) -> ydp_core::Result<()> {
527    /// let (connection, events) = ydp_core::Connection::from_transport(transport, Default::default())?;
528    /// drop(events); drop(connection); Ok(()) }
529    /// ```
530    pub fn from_transport<T: Transport>(
531        transport: T,
532        options: RuntimeOptions,
533    ) -> Result<(Self, RawEventStream)> {
534        let handle =
535            tokio::runtime::Handle::try_current().map_err(|_| Error::new(ErrorKind::NoRuntime))?;
536        validate_options(&options)?;
537        let key = NEXT_CONNECTION
538            .fetch_update(Ordering::Relaxed, Ordering::Relaxed, |v| v.checked_add(1))
539            .map(ConnectionKey)
540            .map_err(|_| {
541                Error::new(ErrorKind::ResourceLimit {
542                    resource: "connection_key",
543                })
544            })?;
545        let root = Arc::new(Route {
546            key: SessionKey {
547                connection: key,
548                sequence: 0,
549            },
550            id: None,
551        });
552        let shared = Arc::new(Shared {
553            key,
554            #[cfg(test)]
555            task: Mutex::new(None),
556            wire_budget: Arc::new(ByteBudget::new(options.limits.wire_bytes)),
557            control: Mutex::new(Control {
558                state: ConnectionState::Open,
559                reason: None,
560                close_started: None,
561                report: None,
562                supplemental_errors: Vec::new(),
563                supplemental_seen: [false; 2],
564                pending: BTreeMap::new(),
565                queues: [VecDeque::new(), VecDeque::new()],
566                counts: [Counts::default(), Counts::default()],
567                waiters: BTreeMap::new(),
568                fifo: [VecDeque::new(), VecDeque::new()],
569                next_waiter: 0,
570                next_request: 1,
571                routes: BTreeMap::new(),
572                retired: Default::default(),
573                next_session: 0,
574                subscriptions: BTreeMap::new(),
575                all: BTreeSet::new(),
576                wild: BTreeMap::new(),
577                exact: BTreeMap::new(),
578                active_keys: BTreeSet::new(),
579                subscription_count: 0,
580                next_subscription: 0,
581                seq: 0,
582                control_streak: 0,
583                closed_pending: 0,
584                closed_outbound: 0,
585            }),
586            outbox: Notify::new(),
587            stop: Notify::new(),
588            closed: Notify::new(),
589            options,
590        });
591        let connection = Self {
592            lease: Arc::new(ApiLease {
593                shared: shared.clone(),
594            }),
595            root,
596        };
597        let events = connection.raw_events(shared.options.initial_events)?;
598        let driver = DriverGuard {
599            transport: Some(transport.split()),
600            outbound_batch: Vec::with_capacity(32),
601            shared: shared.clone(),
602            finished: false,
603        };
604        let task = handle.spawn(run_driver(driver));
605        #[cfg(test)]
606        {
607            *lock(&shared.task) = Some(task);
608        }
609        #[cfg(not(test))]
610        drop(task);
611        Ok((connection, events))
612    }
613    /// 返回本地连接身份,不依赖 endpoint 字符串。
614    /// ```no_run
615    /// fn inspect(c: &ydp_core::Connection) { let _ = c.key(); }
616    /// ```
617    pub fn key(&self) -> ConnectionKey {
618        self.root.key.connection
619    }
620    /// 读取本连接最近分配的入站接收序号,不消费事件,也不发送命令。
621    ///
622    /// 返回值在连接的短控制锁内与响应、事件的序号分配共享仲裁边界。
623    /// 尚未处理任何合法入站 envelope 时返回 `None`;否则返回最近的
624    /// [`ReceiveSeq`],包括已接收但尚未被调用者消费的响应或事件。
625    /// 该值只表示本地接收进度,不证明订阅已消费、上层状态已归并或远端操作完成。
626    ///
627    /// 并发读取可能得到相同值;在同一连接上的先后读取不会倒退。
628    /// 连接关闭后保留最后值;序号耗尽不会回绕。快照之后仍可能立即收到新消息,
629    /// 因此调用者必须自行将此快照与自己的观察登记放在同一同步仲裁边界,
630    /// 不能将它当作跨连接或浏览器因果屏障。此方法不取得新的资源许可,
631    /// 不改变 Clone、Drop 或显式关闭的所有权规则。
632    ///
633    /// # 示例
634    ///
635    /// 使用没有入站消息的内存传输验证初值和关闭后的保留行为;无需浏览器。
636    /// ```
637    /// # use ydp_core::{Connection, MessageReader, MessageWriter, Transport, TransportError};
638    /// # struct Idle;
639    /// # impl MessageReader for Idle {
640    /// #     async fn recv(&mut self) -> Result<Option<bytes::Bytes>, TransportError> {
641    /// #         std::future::pending().await
642    /// #     }
643    /// # }
644    /// # impl MessageWriter for Idle {
645    /// #     async fn send(&mut self, _: bytes::Bytes) -> Result<(), TransportError> { Ok(()) }
646    /// #     async fn flush(&mut self) -> Result<(), TransportError> { Ok(()) }
647    /// #     async fn close(&mut self) -> Result<(), TransportError> { Ok(()) }
648    /// # }
649    /// # impl Transport for Idle {
650    /// #     type Reader = Idle;
651    /// #     type Writer = Idle;
652    /// #     fn split(self) -> (Idle, Idle) { (Idle, Idle) }
653    /// # }
654    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
655    /// # tokio::runtime::Builder::new_current_thread().enable_time().build()?.block_on(async {
656    /// let options = ydp_core::RuntimeOptions {
657    ///     close_timeout: std::time::Duration::ZERO,
658    ///     ..Default::default()
659    /// };
660    /// let (connection, events) = Connection::from_transport(Idle, options)?;
661    /// assert_eq!(connection.latest_receive_seq(), None);
662    /// connection.close().await;
663    /// assert_eq!(connection.latest_receive_seq(), None);
664    /// drop(events);
665    /// # Ok::<(), Box<dyn std::error::Error>>(())
666    /// # }) }
667    /// ```
668    pub fn latest_receive_seq(&self) -> Option<ReceiveSeq> {
669        let sequence = self.lease.shared.control().seq;
670        (sequence != 0).then_some(ReceiveSeq(sequence))
671    }
672    /// 创建根路由视图;不发送协议命令,不假定端点是浏览器。
673    /// ```no_run
674    /// fn inspect(c: &ydp_core::Connection) { assert!(c.root_session().id().is_none()); }
675    /// ```
676    pub fn root_session(&self) -> Session {
677        Session {
678            lease: self.lease.clone(),
679            route: self.root.clone(),
680        }
681    }
682    /// 本地绑定 child ID;活跃 ID 复用记录,retired ID 拒绝,绝不自动 attach。
683    /// ```no_run
684    /// fn adopt(c: &ydp_core::Connection) -> ydp_core::Result<()> { let _ = c.adopt_session(ydp_core::SessionId::new("child".into())?)?; Ok(()) }
685    /// ```
686    pub fn adopt_session(&self, id: SessionId) -> Result<Session> {
687        let s = &self.lease.shared;
688        let route = {
689            let mut c = s.control();
690            Shared::gate(&c, self.root.key)?;
691            if let Some(r) = c.routes.get(&id) {
692                r.clone()
693            } else {
694                if c.retired.contains(&id) {
695                    return Err(Error::new(ErrorKind::SessionIdRetired));
696                }
697                if c.routes.len() >= s.options.limits.active_sessions
698                    || c.routes.len() + c.retired.len() >= s.options.limits.session_records
699                {
700                    return Err(Error::new(ErrorKind::ResourceLimit {
701                        resource: "session_records",
702                    }));
703                }
704                let sequence = c.next_session.checked_add(1).ok_or_else(|| {
705                    Error::new(ErrorKind::ResourceLimit {
706                        resource: "session_key",
707                    })
708                })?;
709                c.next_session = sequence;
710                let r = Arc::new(Route {
711                    key: SessionKey {
712                        connection: self.key(),
713                        sequence,
714                    },
715                    id: Some(id.clone()),
716                });
717                c.active_keys.insert(r.key);
718                c.routes.insert(id, r.clone());
719                r
720            }
721        };
722        Ok(Session {
723            lease: self.lease.clone(),
724            route,
725        })
726    }
727    /// 同步安装 All 订阅,覆盖未知 child;返回前即注册,不回放旧事件。
728    /// ```no_run
729    /// fn subscribe(c: &ydp_core::Connection) -> ydp_core::Result<()> { let _events = c.raw_events(Default::default())?; Ok(()) }
730    /// ```
731    pub fn raw_events(&self, options: SubscriptionOptions) -> Result<RawEventStream> {
732        subscribe(self.lease.clone(), None, None, options)
733    }
734    /// 返回本地生命周期快照。
735    /// ```no_run
736    /// fn inspect(c: &ydp_core::Connection) { let _ = c.state(); }
737    /// ```
738    pub fn state(&self) -> ConnectionState {
739        self.lease.shared.control().state
740    }
741    /// 首次 poll 关门并加入共享退出;丢弃本 Future 不撤销退出。
742    /// ```no_run
743    /// async fn close(c: &ydp_core::Connection) { let report = c.close().await; assert!(report.driver_resources_released); }
744    /// ```
745    pub async fn close(&self) -> CloseReport {
746        self.lease
747            .shared
748            .begin_close(Error::new(ErrorKind::ConnectionClosed));
749        self.closed().await
750    }
751    /// 等待 Driver 释放资源,不主动发起关闭;报告不含用户仍持有的数据。
752    /// ```no_run
753    /// async fn observe(c: &ydp_core::Connection) { let _ = c.closed().await; }
754    /// ```
755    pub async fn closed(&self) -> CloseReport {
756        loop {
757            let n = self.lease.shared.closed.notified();
758            tokio::pin!(n);
759            n.as_mut().enable();
760            if let Some(r) = self.lease.shared.control().report.clone() {
761                return r;
762            }
763            n.await;
764        }
765    }
766}
767/// 在连接建立前验证资源范围,不发生 IO;例如 `validate_options(&RuntimeOptions::default())` 成功,模块测试覆盖零容量拒绝。
768pub(crate) fn validate_options(o: &RuntimeOptions) -> Result<()> {
769    let l = &o.limits;
770    let classes = [l.normal, l.control];
771    if Instant::now().checked_add(o.close_timeout).is_none()
772        || o.initial_events.max_events == 0
773        || o.initial_events.max_bytes == 0
774        || l.max_message_bytes == 0
775        || l.max_message_bytes > 128 << 20
776        || l.wire_bytes == 0
777        || l.max_json_depth == 0
778        || l.max_json_depth > 128
779        || l.subscriptions == 0
780        || l.active_sessions > l.session_records
781        || classes.iter().any(|c| {
782            c.requests == 0
783                || c.outbound_slots == 0
784                || c.max_command_bytes == 0
785                || c.max_command_bytes > c.outbound_bytes
786                || c.requests.checked_add(c.outbound_slots).is_none()
787        })
788    {
789        Err(Error::new(ErrorKind::InvalidArgument))
790    } else {
791        Ok(())
792    }
793}
794
795/// 只管理本地 flattened 路由的廉价 Clone 句柄;Drop 不自动 detach。
796#[derive(Clone)]
797pub struct Session {
798    lease: Arc<ApiLease>,
799    route: Arc<Route>,
800}
801impl Session {
802    /// 返回连接与本地不可重用会话序号。
803    /// ```no_run
804    /// fn inspect(s: &ydp_core::Session) { let _ = s.key(); }
805    /// ```
806    pub fn key(&self) -> SessionKey {
807        self.route.key
808    }
809    /// 借用 child wire ID;根返回 None。
810    /// ```no_run
811    /// fn inspect(s: &ydp_core::Session) { let _ = s.id(); }
812    /// ```
813    pub fn id(&self) -> Option<&SessionId> {
814        self.route.id.as_ref()
815    }
816    /// 查看本地 gate;不证明远端资源已经释放。
817    /// ```no_run
818    /// fn inspect(s: &ydp_core::Session) { let _ = s.is_closed(); }
819    /// ```
820    pub fn is_closed(&self) -> bool {
821        Shared::gate(&self.lease.shared.control(), self.key()).is_err()
822    }
823    /// 同步终结 child 的本地请求和订阅,不发 detach;根发起连接退出。
824    /// 已发布帧仍可能发出;必须由上层管理远端语义责任。
825    /// ```no_run
826    /// fn close(s: &ydp_core::Session) { s.close(); assert!(s.is_closed()); }
827    /// ```
828    pub fn close(&self) {
829        let s = &self.lease.shared;
830        if self.id().is_none() {
831            s.begin_close(Error::new(ErrorKind::ConnectionClosed));
832            return;
833        }
834        let (pending, waiters, subs, removed, ws) = {
835            let mut c = s.control();
836            let Some(id) = self.id() else { return };
837            let removed = c.routes.remove(id);
838            if removed.is_none() {
839                return;
840            }
841            c.active_keys.remove(&self.key());
842            c.retired.insert(id.clone());
843            let ids: Vec<_> = c
844                .pending
845                .iter()
846                .filter(|(_, p)| p.route.key == self.key())
847                .map(|(id, _)| *id)
848                .collect();
849            let pending: Vec<_> = ids
850                .into_iter()
851                .filter_map(|id| c.pending.remove(&id))
852                .collect();
853            let ids: Vec<_> = c
854                .waiters
855                .iter()
856                .filter(|(_, w)| w.route == self.key())
857                .map(|(id, _)| *id)
858                .collect();
859            let mut waiters = Vec::new();
860            for id in ids {
861                if let Some(w) = c.waiters.remove(&id) {
862                    c.counts[w.class].waiters -= 1;
863                    if w.granted {
864                        c.counts[w.class].requests -= 1;
865                        c.counts[w.class].slots -= 1;
866                    }
867                    c.fifo[w.class].retain(|v| *v != id);
868                    waiters.push(w);
869                }
870            }
871            let ids: Vec<_> = c
872                .subscriptions
873                .iter()
874                .filter(|(_, v)| v.route == Some(self.key()))
875                .map(|(id, _)| *id)
876                .collect();
877            let subs: Vec<_> = ids
878                .into_iter()
879                .filter_map(|id| c.remove_subscription(id))
880                .collect();
881            let ws = s.grant(&mut c);
882            (pending, waiters, subs, removed, ws)
883        };
884        drop(removed);
885        for p in pending {
886            let _ = p.sender.send(Delivery {
887                result: Err(Error::new(ErrorKind::SessionClosed)),
888                _permit: p.permit,
889            });
890        }
891        for w in waiters {
892            if let Some(w) = w.waker {
893                w.wake();
894            }
895        }
896        for sub in subs {
897            sub.terminate(Error::new(ErrorKind::SessionClosed));
898        }
899        wake(ws);
900    }
901    /// 创建拥有参数的冷请求;首次 poll 前没有编码、ID 或网络副作用。
902    /// ```no_run
903    /// fn send<C: ydp_core::Command>(s: &ydp_core::Session, params: C::Params) { let _request = s.send::<C>(params); }
904    /// ```
905    pub fn send<C: Command>(&self, params: C::Params) -> Request<C> {
906        self.send_with::<C>(params, RequestOptions::default())
907    }
908    /// 使用指定期限和独立流量类别创建同一种冷请求;不重试。
909    /// ```no_run
910    /// fn send<C: ydp_core::Command>(s: &ydp_core::Session, params: C::Params) { let _request = s.send_with::<C>(params, Default::default()); }
911    /// ```
912    pub fn send_with<C: Command>(&self, params: C::Params, options: RequestOptions) -> Request<C> {
913        Request {
914            inner: RequestBody::new(
915                self.clone(),
916                std::borrow::Cow::Borrowed(C::METHOD),
917                params,
918                options,
919            ),
920            marker: PhantomData,
921        }
922    }
923    /// 创建动态方法请求;参数在首次 poll 校验为 JSON object。
924    /// ```no_run
925    /// fn send(s: &ydp_core::Session) -> ydp_core::Result<()> { let params=ydp_core::RawJson::from_bytes(bytes::Bytes::from_static(b"{}"))?; let _request=s.send_raw(ydp_core::MethodName::new("Echo.echo".into())?,params,Default::default()); Ok(()) }
926    /// ```
927    pub fn send_raw(
928        &self,
929        method: MethodName,
930        params: RawJson,
931        options: RequestOptions,
932    ) -> RawRequest {
933        RawRequest {
934            inner: RequestBody::new(
935                self.clone(),
936                std::borrow::Cow::Owned(method.as_str().to_owned()),
937                params,
938                options,
939            ),
940        }
941    }
942    /// 同步安装精确 Session 与 METHOD 订阅;消费时才解码,不自动 enable。
943    /// ```no_run
944    /// fn subscribe<E: ydp_core::Event>(s: &ydp_core::Session) -> ydp_core::Result<()> { let _events=s.events::<E>(Default::default())?; Ok(()) }
945    /// ```
946    pub fn events<E: Event>(&self, options: SubscriptionOptions) -> Result<EventStream<E>> {
947        Ok(EventStream {
948            raw: subscribe(
949                self.lease.clone(),
950                Some(self.key()),
951                Some(E::METHOD),
952                options,
953            )?,
954            key: self.key(),
955            marker: PhantomData,
956        })
957    }
958    /// 同步安装精确本地 Session 的所有方法订阅。
959    /// ```no_run
960    /// fn subscribe(s: &ydp_core::Session) -> ydp_core::Result<()> { let _events=s.raw_events(Default::default())?; Ok(()) }
961    /// ```
962    pub fn raw_events(&self, options: SubscriptionOptions) -> Result<RawEventStream> {
963        subscribe(self.lease.clone(), Some(self.key()), None, options)
964    }
965}
966
967struct RequestCore<P> {
968    session: Option<Session>,
969    key: SessionKey,
970    method: std::borrow::Cow<'static, str>,
971    params: Option<P>,
972    options: RequestOptions,
973    guard: Option<Guard>,
974    receiver: Option<oneshot::Receiver<Delivery>>,
975    deadline: Option<Instant>,
976    started: bool,
977    done: bool,
978    submission: Submission,
979    id: Option<RequestId>,
980    seq: Option<ReceiveSeq>,
981}
982pin_project! {struct RequestBody<P> {core:RequestCore<P>,#[pin] timer:Option<Sleep>}}
983impl<P> RequestBody<P> {
984    fn new(
985        session: Session,
986        method: std::borrow::Cow<'static, str>,
987        params: P,
988        options: RequestOptions,
989    ) -> Self {
990        let key = session.key();
991        let guard = Guard {
992            shared: Arc::downgrade(&session.lease.shared),
993            waiter: None,
994            id: None,
995        };
996        Self {
997            core: RequestCore {
998                session: Some(session),
999                key,
1000                method,
1001                params: Some(params),
1002                options,
1003                guard: Some(guard),
1004                receiver: None,
1005                deadline: None,
1006                started: false,
1007                done: false,
1008                submission: Submission::NotSubmitted,
1009                id: None,
1010                seq: None,
1011            },
1012            timer: None,
1013        }
1014    }
1015}
1016impl<P> RequestCore<P> {
1017    fn context(&self) -> RequestContext {
1018        RequestContext {
1019            method: self.method.to_string(),
1020            request_id: self.id,
1021            session_key: self.key,
1022            submission: self.submission,
1023            receive_seq: self.seq,
1024        }
1025    }
1026    fn error(&self, mut e: Error) -> Error {
1027        e.context = Some(Box::new(self.context()));
1028        e
1029    }
1030    fn expired(&self) -> bool {
1031        self.deadline.is_some_and(|d| Instant::now() >= d)
1032    }
1033    fn finish(&mut self) {
1034        self.done = true;
1035        self.guard.take();
1036        self.receiver.take();
1037        self.params.take();
1038        self.session.take();
1039    }
1040}
1041impl<P: serde::Serialize> RequestBody<P> {
1042    fn poll_delivery(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<Delivery>> {
1043        let mut this = self.project();
1044        let c = this.core;
1045        if c.done {
1046            return Poll::Pending;
1047        }
1048        if !c.started {
1049            c.started = true;
1050            c.deadline = match c.options.timeout {
1051                Timeout::Unlimited => None,
1052                Timeout::After(d) => match Instant::now().checked_add(d) {
1053                    Some(deadline) => Some(deadline),
1054                    None => {
1055                        let e = c.error(Error::new(ErrorKind::InvalidArgument));
1056                        c.finish();
1057                        return Poll::Ready(Err(e));
1058                    }
1059                },
1060                Timeout::At(d) => Some(d),
1061            };
1062            if let Some(d) = c.deadline {
1063                this.timer.set(Some(tokio::time::sleep_until(d)));
1064            }
1065        }
1066        if c.expired() {
1067            let e = c.error(Error::new(ErrorKind::Timeout));
1068            c.finish();
1069            return Poll::Ready(Err(e));
1070        }
1071        if let Some(timer) = this.timer.as_mut().as_pin_mut() {
1072            let _ = timer.poll(cx);
1073        }
1074        if c.receiver.is_none() {
1075            let Some(session) = c.session.as_ref() else {
1076                return Poll::Pending;
1077            };
1078            let shared = session.lease.shared.clone();
1079            let route = session.route.clone();
1080            let class = c.options.traffic_class.index();
1081            let Some(guard) = c.guard.as_mut() else {
1082                return Poll::Pending;
1083            };
1084            let (request_permit, outbound_permit) = match shared.admission(c.key, class, guard, cx)
1085            {
1086                Poll::Pending => return Poll::Pending,
1087                Poll::Ready(Err(e)) => {
1088                    let e = c.error(e);
1089                    c.finish();
1090                    return Poll::Ready(Err(e));
1091                }
1092                Poll::Ready(Ok(p)) => p,
1093            };
1094            let id = {
1095                let mut control = shared.control();
1096                if control.next_request > i64::from(i32::MAX) {
1097                    None
1098                } else {
1099                    let id = control.next_request as i32;
1100                    control.next_request += 1;
1101                    Some(id)
1102                }
1103            };
1104            let Some(id) = id else {
1105                let e = c.error(Error::new(ErrorKind::IdExhausted));
1106                c.finish();
1107                return Poll::Ready(Err(e));
1108            };
1109            c.id = Some(RequestId(id));
1110            let mut writer = BudgetWriter {
1111                shared: shared.clone(),
1112                permit: outbound_permit,
1113                bytes: Vec::new(),
1114                limit: shared.class(class).max_command_bytes,
1115                exceeded: false,
1116            };
1117            let Some(params) = c.params.take() else {
1118                return Poll::Pending;
1119            };
1120            let encoded = crate::wire::encode(
1121                id,
1122                &c.method,
1123                route.id.as_ref().map(SessionId::as_str),
1124                &params,
1125                &mut writer,
1126            );
1127            drop(params);
1128            if let Err(e) = encoded {
1129                let e = if writer.exceeded {
1130                    Error::new(ErrorKind::ResourceLimit {
1131                        resource: "outbound_bytes",
1132                    })
1133                } else {
1134                    e
1135                };
1136                let e = c.error(e);
1137                c.finish();
1138                return Poll::Ready(Err(e));
1139            }
1140            if c.expired() {
1141                let e = c.error(Error::new(ErrorKind::Timeout));
1142                c.finish();
1143                return Poll::Ready(Err(e));
1144            }
1145            let (sender, receiver) = oneshot::channel();
1146            let mut pending = Some(Pending {
1147                route,
1148                sender,
1149                permit: request_permit,
1150            });
1151            let mut outbound = Some(Outbound {
1152                bytes: Bytes::from(writer.bytes),
1153                _permit: writer.permit,
1154            });
1155            let result = {
1156                let mut control = shared.control();
1157                Shared::gate(&control, c.key).and_then(|()| {
1158                    if c.expired() {
1159                        Err(Error::new(ErrorKind::Timeout))
1160                    } else {
1161                        if let Some(p) = pending.take() {
1162                            control.pending.insert(id, p);
1163                        }
1164                        if let Some(o) = outbound.take() {
1165                            control.queues[class].push_back(o);
1166                        }
1167                        c.submission = Submission::PossiblySent;
1168                        if let Some(g) = c.guard.as_mut() {
1169                            g.id = Some(id);
1170                        }
1171                        Ok(())
1172                    }
1173                })
1174            };
1175            drop(pending);
1176            drop(outbound);
1177            if let Err(e) = result {
1178                let e = c.error(e);
1179                c.finish();
1180                return Poll::Ready(Err(e));
1181            }
1182            c.receiver = Some(receiver);
1183            shared.outbox.notify_one();
1184        }
1185        let Some(receiver) = c.receiver.as_mut() else {
1186            return Poll::Pending;
1187        };
1188        match Pin::new(receiver).poll(cx) {
1189            Poll::Pending => Poll::Pending,
1190            Poll::Ready(Err(_)) => {
1191                let e = c.error(Error::new(ErrorKind::DriverFailed));
1192                c.finish();
1193                Poll::Ready(Err(e))
1194            }
1195            Poll::Ready(Ok(delivery)) => {
1196                if let Ok(reply) = &delivery.result {
1197                    c.seq = Some(reply.receive_seq);
1198                    c.submission = Submission::Responded;
1199                } else if let Err(e) = &delivery.result
1200                    && let Some(context) = &e.context
1201                    && context.receive_seq.is_some()
1202                {
1203                    c.seq = context.receive_seq;
1204                    c.submission = context.submission;
1205                }
1206                c.finish();
1207                Poll::Ready(Ok(delivery))
1208            }
1209        }
1210    }
1211}
1212pin_project! {
1213    /// 拥有参数的冷 typed Future;完成后再次 poll 返回 Pending,Drop 仅取消本地等待。
1214    #[must_use = "请求必须被 poll 才会提交"]
1215    pub struct Request<C:Command> {#[pin] inner:RequestBody<C::Params>,marker:PhantomData<fn()->C>}
1216}
1217impl<C: Command> Request<C> {
1218    /// 返回保守发送证据;PossiblySent 不允许据此自动重放。
1219    /// ```no_run
1220    /// fn inspect<C: ydp_core::Command>(r: &ydp_core::Request<C>) { let _ = r.submission(); }
1221    /// ```
1222    pub fn submission(&self) -> Submission {
1223        self.inner.core.submission
1224    }
1225    /// 返回已分配 ID;冷请求为 None,编码失败可能留下合法 ID 空洞。
1226    /// ```no_run
1227    /// fn inspect<C: ydp_core::Command>(r: &ydp_core::Request<C>) { let _ = r.request_id(); }
1228    /// ```
1229    pub fn request_id(&self) -> Option<RequestId> {
1230        self.inner.core.id
1231    }
1232}
1233impl<C: Command> Future for Request<C> {
1234    type Output = Result<C::Response>;
1235    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
1236        let mut this = self.project();
1237        match this.inner.as_mut().poll_delivery(cx) {
1238            Poll::Pending => Poll::Pending,
1239            Poll::Ready(Err(e)) => Poll::Ready(Err(e)),
1240            Poll::Ready(Ok(delivery)) => {
1241                let Delivery { result, _permit } = delivery;
1242                let result = result.and_then(|reply| reply.result.decode());
1243                let core = &this.inner.as_ref().get_ref().core;
1244                let result = if core.expired() {
1245                    Err(Error::new(ErrorKind::Timeout))
1246                } else {
1247                    result
1248                };
1249                Poll::Ready(result.map_err(|e| core.error(e)))
1250            }
1251        }
1252    }
1253}
1254impl<C: Command> FusedFuture for Request<C> {
1255    fn is_terminated(&self) -> bool {
1256        self.inner.core.done
1257    }
1258}
1259pin_project! {
1260    /// 动态方法的拥有型冷 Future,与 typed Request 共享准入和取消路径。
1261    #[must_use = "请求必须被 poll 才会提交"]
1262    pub struct RawRequest {#[pin] inner:RequestBody<RawJson>}
1263}
1264impl RawRequest {
1265    /// 返回保守发送证据;不表示远端执行状态。
1266    /// ```no_run
1267    /// fn inspect(r: &ydp_core::RawRequest) { let _ = r.submission(); }
1268    /// ```
1269    pub fn submission(&self) -> Submission {
1270        self.inner.core.submission
1271    }
1272    /// 返回已分配的请求 ID,首次 poll 前为 None。
1273    /// ```no_run
1274    /// fn inspect(r: &ydp_core::RawRequest) { let _ = r.request_id(); }
1275    /// ```
1276    pub fn request_id(&self) -> Option<RequestId> {
1277        self.inner.core.id
1278    }
1279}
1280impl Future for RawRequest {
1281    type Output = Result<RawReply>;
1282    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
1283        let mut this = self.project();
1284        match this.inner.as_mut().poll_delivery(cx) {
1285            Poll::Pending => Poll::Pending,
1286            Poll::Ready(Err(e)) => Poll::Ready(Err(e)),
1287            Poll::Ready(Ok(d)) => Poll::Ready(
1288                d.result
1289                    .map_err(|e| this.inner.as_ref().get_ref().core.error(e)),
1290            ),
1291        }
1292    }
1293}
1294impl FusedFuture for RawRequest {
1295    fn is_terminated(&self) -> bool {
1296        self.inner.core.done
1297    }
1298}
1299/// 原始成功响应;结果共享 backing frame,Drop 最后引用才释放 wire 配额。
1300#[derive(Clone, Debug)]
1301pub struct RawReply {
1302    /// 关联的请求 ID。
1303    pub request_id: RequestId,
1304    /// 已登记的本地会话身份。
1305    pub session_key: SessionKey,
1306    /// 该响应的连接接收序号。
1307    pub receive_seq: ReceiveSeq,
1308    /// 原始结果 object。
1309    pub result: RawJson,
1310}
1311/// 已绑定本地 Session 的 typed 事件及连接接收顺序。
1312#[derive(Debug)]
1313pub struct EventEnvelope<T> {
1314    /// 精确订阅时的本地路由身份。
1315    pub session_key: SessionKey,
1316    /// 原始 envelope 的本地接收序号。
1317    pub receive_seq: ReceiveSeq,
1318    /// 在消费者任务解码的拥有型数据。
1319    pub params: T,
1320}
1321#[derive(Clone)]
1322enum MethodText {
1323    Shared(FrameText),
1324    Owned(Arc<str>),
1325}
1326impl MethodText {
1327    fn as_str(&self) -> &str {
1328        match self {
1329            Self::Shared(text) => text.as_str(),
1330            Self::Owned(text) => text,
1331        }
1332    }
1333}
1334/// 共享原始事件,保留未知 child 来源而不伪造 SessionKey。
1335#[derive(Clone)]
1336pub struct RawEvent {
1337    connection: ConnectionKey,
1338    session: Option<SessionId>,
1339    seq: ReceiveSeq,
1340    method: MethodText,
1341    params: RawJson,
1342    frame_len: usize,
1343}
1344impl std::fmt::Debug for RawEvent {
1345    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1346        f.debug_struct("RawEvent")
1347            .field("connection", &self.connection)
1348            .field("session", &self.session)
1349            .field("seq", &self.seq)
1350            .field("method", &self.method.as_str())
1351            .field("frame_len", &self.frame_len)
1352            .finish_non_exhaustive()
1353    }
1354}
1355impl RawEvent {
1356    /// 返回来源连接身份。
1357    /// ```no_run
1358    /// fn inspect(e: &ydp_core::RawEvent) { let _ = e.connection_key(); }
1359    /// ```
1360    pub fn connection_key(&self) -> ConnectionKey {
1361        self.connection
1362    }
1363    /// 借用原始 child 路由 ID;未知 child 仍保留,根为 None。
1364    /// ```no_run
1365    /// fn inspect(e: &ydp_core::RawEvent) { let _ = e.session_id(); }
1366    /// ```
1367    pub fn session_id(&self) -> Option<&SessionId> {
1368        self.session.as_ref()
1369    }
1370    /// 返回连接内接收序;事件流允许响应造成的空洞。
1371    /// ```no_run
1372    /// fn inspect(e: &ydp_core::RawEvent) { let _ = e.receive_seq(); }
1373    /// ```
1374    pub fn receive_seq(&self) -> ReceiveSeq {
1375        self.seq
1376    }
1377    /// 借用已正确反转义的完整方法名。
1378    /// ```no_run
1379    /// fn inspect(e: &ydp_core::RawEvent) { let _ = e.method(); }
1380    /// ```
1381    pub fn method(&self) -> &str {
1382        self.method.as_str()
1383    }
1384    /// 借用共享参数 object;省略 params 时为同 backing 生命周期的空 object。
1385    /// ```no_run
1386    /// fn inspect(e: &ydp_core::RawEvent) { let _ = e.params().as_bytes(); }
1387    /// ```
1388    pub fn params(&self) -> &RawJson {
1389        &self.params
1390    }
1391}
1392struct Subscriber {
1393    shared: Weak<Shared>,
1394    route: Option<SessionKey>,
1395    method: Option<&'static str>,
1396    options: SubscriptionOptions,
1397    state: Mutex<SubState>,
1398    waker: AtomicWaker,
1399}
1400struct SubState {
1401    queue: VecDeque<RawEvent>,
1402    bytes: usize,
1403    terminal: Option<Error>,
1404    ended: bool,
1405}
1406impl Subscriber {
1407    fn state(&self) -> MutexGuard<'_, SubState> {
1408        match self.state.lock() {
1409            Ok(guard) => guard,
1410            Err(poisoned) => {
1411                drop(poisoned.into_inner());
1412                self.state.clear_poison();
1413                if let Some(shared) = self.shared.upgrade() {
1414                    shared.begin_close(Error::new(ErrorKind::DriverFailed));
1415                }
1416                self.terminate(Error::new(ErrorKind::DriverFailed));
1417                lock(&self.state)
1418            }
1419        }
1420    }
1421
1422    fn terminate(&self, error: Error) {
1423        let should_wake = {
1424            let mut s = self.state();
1425            if s.ended || s.terminal.is_some() {
1426                false
1427            } else {
1428                s.terminal = Some(error);
1429                true
1430            }
1431        };
1432        if should_wake {
1433            self.waker.wake();
1434        }
1435    }
1436    fn deliver(&self, event: RawEvent) -> bool {
1437        let mut owned = Some(event);
1438        let live = {
1439            let mut s = self.state();
1440            if s.ended || s.terminal.is_some() {
1441                false
1442            } else {
1443                let len = owned.as_ref().map_or(0, |e| e.frame_len);
1444                if s.queue.len() >= self.options.max_events
1445                    || s.bytes
1446                        .checked_add(len)
1447                        .is_none_or(|v| v > self.options.max_bytes)
1448                {
1449                    s.terminal = Some(Error::new(ErrorKind::EventBufferFull));
1450                    false
1451                } else {
1452                    s.bytes += len;
1453                    if let Some(event) = owned.take() {
1454                        s.queue.push_back(event);
1455                    }
1456                    true
1457                }
1458            }
1459        };
1460        drop(owned);
1461        self.waker.wake();
1462        live
1463    }
1464    fn discard(&self) {
1465        let queue = {
1466            let mut s = self.state();
1467            s.ended = true;
1468            s.bytes = 0;
1469            std::mem::take(&mut s.queue)
1470        };
1471        drop(queue);
1472    }
1473}
1474fn subscribe(
1475    lease: Arc<ApiLease>,
1476    route: Option<SessionKey>,
1477    method: Option<&'static str>,
1478    options: SubscriptionOptions,
1479) -> Result<RawEventStream> {
1480    if options.max_events == 0 || options.max_bytes == 0 {
1481        return Err(Error::new(ErrorKind::InvalidArgument));
1482    }
1483    let subscriber = Arc::new(Subscriber {
1484        shared: Arc::downgrade(&lease.shared),
1485        route,
1486        method,
1487        options,
1488        state: Mutex::new(SubState {
1489            queue: VecDeque::new(),
1490            bytes: 0,
1491            terminal: None,
1492            ended: false,
1493        }),
1494        waker: AtomicWaker::new(),
1495    });
1496    let id = {
1497        let shared = &lease.shared;
1498        let mut c = shared.control();
1499        if c.state != ConnectionState::Open {
1500            return Err(Error::new(ErrorKind::ConnectionClosed));
1501        }
1502        if let Some(key) = route {
1503            Shared::gate(&c, key)?;
1504        }
1505        if c.subscription_count >= shared.options.limits.subscriptions {
1506            return Err(Error::new(ErrorKind::ResourceLimit {
1507                resource: "subscriptions",
1508            }));
1509        }
1510        let id = c.next_subscription.checked_add(1).ok_or_else(|| {
1511            Error::new(ErrorKind::ResourceLimit {
1512                resource: "subscription_id",
1513            })
1514        })?;
1515        c.next_subscription = id;
1516        c.subscription_count += 1;
1517        match route {
1518            None => {
1519                c.all.insert(id);
1520            }
1521            Some(key) => {
1522                if let Some(method) = method {
1523                    c.exact
1524                        .entry(key)
1525                        .or_default()
1526                        .entry(method)
1527                        .or_default()
1528                        .insert(id);
1529                } else {
1530                    c.wild.entry(key).or_default().insert(id);
1531                }
1532            }
1533        }
1534        c.subscriptions.insert(id, subscriber.clone());
1535        id
1536    };
1537    Ok(RawEventStream {
1538        lease,
1539        subscriber,
1540        id,
1541    })
1542}
1543/// 有界原始事件订阅;终态优先于积压数据,Drop 静默退订自身。
1544pub struct RawEventStream {
1545    lease: Arc<ApiLease>,
1546    subscriber: Arc<Subscriber>,
1547    id: u64,
1548}
1549impl Drop for RawEventStream {
1550    fn drop(&mut self) {
1551        let removed = {
1552            let mut c = self.lease.shared.control();
1553            c.subscription_count -= 1;
1554            c.remove_subscription(self.id)
1555        };
1556        self.subscriber.discard();
1557        drop(removed);
1558    }
1559}
1560impl Stream for RawEventStream {
1561    type Item = Result<RawEvent>;
1562    fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
1563        let this = self.get_mut();
1564        this.subscriber.waker.register(cx.waker());
1565        let (result, discarded) = {
1566            let mut s = this.subscriber.state();
1567            if s.ended {
1568                (Poll::Ready(None), None)
1569            } else if let Some(error) = s.terminal.take() {
1570                s.ended = true;
1571                s.bytes = 0;
1572                (
1573                    Poll::Ready(Some(Err(error))),
1574                    Some(std::mem::take(&mut s.queue)),
1575                )
1576            } else if let Some(event) = s.queue.pop_front() {
1577                s.bytes -= event.frame_len;
1578                (Poll::Ready(Some(Ok(event))), None)
1579            } else {
1580                (Poll::Pending, None)
1581            }
1582        };
1583        drop(discarded);
1584        result
1585    }
1586}
1587/// 精确 typed 订阅;解码失败仅终结当前流,不影响其他 raw/typed 消费者。
1588pub struct EventStream<E: Event> {
1589    raw: RawEventStream,
1590    key: SessionKey,
1591    marker: PhantomData<fn() -> E>,
1592}
1593impl<E: Event> Stream for EventStream<E> {
1594    type Item = Result<EventEnvelope<E::Params>>;
1595    fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
1596        let this = self.get_mut();
1597        match Pin::new(&mut this.raw).poll_next(cx) {
1598            Poll::Pending => Poll::Pending,
1599            Poll::Ready(None) => Poll::Ready(None),
1600            Poll::Ready(Some(Err(e))) => Poll::Ready(Some(Err(e))),
1601            Poll::Ready(Some(Ok(event))) => match event.params.decode() {
1602                Ok(params) => Poll::Ready(Some(Ok(EventEnvelope {
1603                    session_key: this.key,
1604                    receive_seq: event.seq,
1605                    params,
1606                }))),
1607                Err(mut e) => {
1608                    e.context = Some(Box::new(RequestContext {
1609                        method: event.method.as_str().to_owned(),
1610                        request_id: None,
1611                        session_key: this.key,
1612                        submission: Submission::Responded,
1613                        receive_seq: Some(event.seq),
1614                    }));
1615                    this.raw.subscriber.discard();
1616                    let removed = this
1617                        .raw
1618                        .lease
1619                        .shared
1620                        .control()
1621                        .remove_subscription(this.raw.id);
1622                    drop(removed);
1623                    Poll::Ready(Some(Err(e)))
1624                }
1625            },
1626        }
1627    }
1628}
1629
1630struct DriverGuard<R: MessageReader, W: MessageWriter> {
1631    transport: Option<(R, W)>,
1632    outbound_batch: Vec<Outbound>,
1633    shared: Arc<Shared>,
1634    finished: bool,
1635}
1636impl<R: MessageReader, W: MessageWriter> Drop for DriverGuard<R, W> {
1637    fn drop(&mut self) {
1638        drop(self.transport.take());
1639        self.outbound_batch.clear();
1640        if !self.finished {
1641            self.shared.begin_close(Error::new(ErrorKind::DriverFailed));
1642            self.shared.finish(TransportEnd::Failed);
1643        }
1644    }
1645}
1646async fn run_driver<R: MessageReader, W: MessageWriter>(mut guard: DriverGuard<R, W>) {
1647    let shared = guard.shared.clone();
1648    let failure = {
1649        let Some((reader, writer)) = guard.transport.as_mut() else {
1650            return;
1651        };
1652        let read = read_loop(reader, &shared);
1653        let write = write_loop(writer, &shared, &mut guard.outbound_batch);
1654        tokio::pin!(read, write);
1655        tokio::select! {r=&mut read=>Some((0,r)),r=&mut write=>Some((1,r)),()=shared.stopped()=>None}
1656    };
1657    if let Some((direction, error)) = failure
1658        && !shared.begin_close(error.clone())
1659        && matches!(error.kind, ErrorKind::Transport)
1660    {
1661        shared.supplement(direction, error);
1662    }
1663    let deadline = {
1664        let c = shared.control();
1665        c.close_started
1666            .and_then(|t| t.checked_add(shared.options.close_timeout))
1667            .unwrap_or_else(Instant::now)
1668    };
1669    let end = if let Some((reader, writer)) = guard.transport.as_mut() {
1670        let close = async {
1671            let read = async {
1672                let mut count = 0usize;
1673                let mut since = Instant::now();
1674                loop {
1675                    match reader.recv().await {
1676                        Ok(Some(_)) => {}
1677                        Ok(None) => return true,
1678                        Err(error) => {
1679                            shared.supplement(0, Error::with_source(ErrorKind::Transport, error));
1680                            return false;
1681                        }
1682                    }
1683                    count += 1;
1684                    if count >= 256 || since.elapsed() >= Duration::from_millis(2) {
1685                        tokio::task::yield_now().await;
1686                        count = 0;
1687                        since = Instant::now();
1688                    }
1689                }
1690            };
1691            let write = async {
1692                match writer.close().await {
1693                    Ok(()) => true,
1694                    Err(error) => {
1695                        shared.supplement(1, Error::with_source(ErrorKind::Transport, error));
1696                        false
1697                    }
1698                }
1699            };
1700            let (read_ok, write_ok) = tokio::join!(read, write);
1701            read_ok && write_ok
1702        };
1703        match tokio::time::timeout_at(deadline, close).await {
1704            Ok(true) => TransportEnd::Graceful,
1705            Ok(false) => TransportEnd::Failed,
1706            Err(_) => TransportEnd::Aborted,
1707        }
1708    } else {
1709        TransportEnd::Failed
1710    };
1711    drop(guard.transport.take());
1712    guard.outbound_batch.clear();
1713    shared.finish(end);
1714    guard.finished = true;
1715}
1716async fn read_loop<R: MessageReader>(reader: &mut R, shared: &Arc<Shared>) -> Error {
1717    let mut processed = 0usize;
1718    let mut since = Instant::now();
1719    loop {
1720        let bytes = match reader.recv().await {
1721            Ok(Some(b)) => b,
1722            Ok(None) => return Error::new(ErrorKind::ConnectionClosed),
1723            Err(e) => return Error::with_source(ErrorKind::Transport, e),
1724        };
1725        if let Err(e) = receive(shared, bytes) {
1726            return e;
1727        }
1728        processed += 1;
1729        if processed >= 256 || since.elapsed() >= Duration::from_millis(2) {
1730            tokio::task::yield_now().await;
1731            processed = 0;
1732            since = Instant::now();
1733        }
1734    }
1735}
1736async fn write_loop<W: MessageWriter>(
1737    writer: &mut W,
1738    shared: &Arc<Shared>,
1739    batch: &mut Vec<Outbound>,
1740) -> Error {
1741    let mut processed = 0usize;
1742    let mut since = Instant::now();
1743    loop {
1744        let notification = shared.outbox.notified();
1745        tokio::pin!(notification);
1746        notification.as_mut().enable();
1747        let Some(first) = shared.pop() else {
1748            notification.await;
1749            continue;
1750        };
1751        let mut size = 0;
1752        let mut next = Some(first);
1753        while let Some(frame) = next {
1754            size += frame.bytes.len();
1755            let bytes = frame.bytes.clone();
1756            batch.push(frame);
1757            if let Err(e) = writer.send(bytes).await {
1758                return Error::with_source(ErrorKind::Transport, e);
1759            }
1760            if batch.len() >= 32 || size >= 64 << 10 {
1761                break;
1762            }
1763            next = shared.pop_with_budget(Some((64 << 10) - size));
1764        }
1765        if let Err(e) = writer.flush().await {
1766            return Error::with_source(ErrorKind::Transport, e);
1767        }
1768        processed += batch.len();
1769        batch.clear();
1770        if processed >= 256 || since.elapsed() >= Duration::from_millis(2) {
1771            tokio::task::yield_now().await;
1772            processed = 0;
1773            since = Instant::now();
1774        }
1775    }
1776}
1777fn receive(shared: &Arc<Shared>, bytes: Bytes) -> Result<()> {
1778    let envelope = crate::wire::parse(
1779        &bytes,
1780        shared.options.limits.max_message_bytes,
1781        shared.options.limits.max_json_depth,
1782    )?;
1783    let (seq, pending, response_session_mismatch, targets, connection, known_session) = {
1784        let mut c = shared.control();
1785        if c.state != ConnectionState::Open {
1786            return Ok(());
1787        }
1788        c.seq = c.seq.checked_add(1).ok_or_else(|| {
1789            Error::new(ErrorKind::ResourceLimit {
1790                resource: "receive_seq",
1791            })
1792        })?;
1793        let seq = ReceiveSeq(c.seq);
1794        if let Some(id) = envelope.id {
1795            let pending = c.pending.remove(&id);
1796            let response_session_mismatch = pending.as_ref().is_some_and(|pending| {
1797                pending.route.id.as_ref().map(SessionId::as_str) != envelope.session_id.as_deref()
1798            });
1799            (
1800                seq,
1801                pending,
1802                response_session_mismatch,
1803                Vec::new(),
1804                None,
1805                None,
1806            )
1807        } else {
1808            let session = envelope
1809                .session_id
1810                .as_deref()
1811                .and_then(|id| c.routes.get(id))
1812                .map(|r| (r.id.clone(), r.key));
1813            let key = if envelope.session_id.is_none() {
1814                Some(SessionKey {
1815                    connection: shared.key,
1816                    sequence: 0,
1817                })
1818            } else {
1819                session.as_ref().map(|(_, k)| *k)
1820            };
1821            let mut ids = c.all.iter().copied().collect::<Vec<_>>();
1822            if let Some(key) = key {
1823                if let Some(wild) = c.wild.get(&key) {
1824                    ids.extend(wild.iter().copied());
1825                }
1826                if let Some(method) = envelope.method.as_deref()
1827                    && let Some(exact) = c.exact.get(&key).and_then(|methods| methods.get(method))
1828                {
1829                    ids.extend(exact.iter().copied());
1830                }
1831            }
1832            let targets = ids
1833                .into_iter()
1834                .filter_map(|id| c.subscriptions.get(&id).map(|s| (id, s.clone())))
1835                .collect::<Vec<_>>();
1836            let connection = targets
1837                .first()
1838                .and_then(|(_, s)| s.route.map(|k| k.connection));
1839            (
1840                seq,
1841                None,
1842                false,
1843                targets,
1844                connection,
1845                session.and_then(|(id, _)| id),
1846            )
1847        }
1848    };
1849    if let Some(pending) = pending {
1850        if response_session_mismatch {
1851            // request ID 在连接内唯一,足以安全终结原 pending;错路由 payload 仍完全拒绝,
1852            // 但 Chromium 在 child 退役后可能把迟到响应放到根 envelope,不能因此破坏其他路由。
1853            let mut error = Error::new(ErrorKind::ResponseSessionMismatch);
1854            error.context = Some(Box::new(RequestContext {
1855                method: String::new(),
1856                request_id: envelope.id.map(RequestId),
1857                session_key: pending.route.key,
1858                submission: Submission::PossiblySent,
1859                receive_seq: Some(seq),
1860            }));
1861            let _ = pending.sender.send(Delivery {
1862                result: Err(error),
1863                _permit: pending.permit,
1864            });
1865            return Ok(());
1866        }
1867        let prepared: Result<Result<RawReply>> = (|| {
1868            let frame = Frame::new(bytes.clone(), shared.wire_budget.clone())?;
1869            if let Some(result) = envelope.result {
1870                Ok(Ok(RawReply {
1871                    request_id: RequestId(
1872                        envelope
1873                            .id
1874                            .ok_or_else(|| Error::new(ErrorKind::InvalidMessage))?,
1875                    ),
1876                    session_key: pending.route.key,
1877                    receive_seq: seq,
1878                    result: frame.json(result)?,
1879                }))
1880            } else if let Some(error) = envelope.error {
1881                let mut error = Error::new(ErrorKind::Protocol {
1882                    code: error.code,
1883                    message: error.message.into_owned(),
1884                    data: error.data.map(|raw| frame.json(raw)).transpose()?,
1885                });
1886                error.retain_frame(frame);
1887                error.context = Some(Box::new(RequestContext {
1888                    method: String::new(),
1889                    request_id: envelope.id.map(RequestId),
1890                    session_key: pending.route.key,
1891                    submission: Submission::Responded,
1892                    receive_seq: Some(seq),
1893                }));
1894                Ok(Err(error))
1895            } else {
1896                Err(Error::new(ErrorKind::InvalidMessage))
1897            }
1898        })();
1899        let (result, failure) = match prepared {
1900            Ok(result) => (result, None),
1901            Err(error) => (Err(error.clone()), Some(error)),
1902        };
1903        let _ = pending.sender.send(Delivery {
1904            result,
1905            _permit: pending.permit,
1906        });
1907        if let Some(error) = failure {
1908            return Err(error);
1909        }
1910    } else if !targets.is_empty() {
1911        let frame = Frame::new(bytes.clone(), shared.wire_budget.clone())?;
1912        let params = match envelope.params {
1913            Some(raw) => frame.json(raw)?,
1914            None => frame.empty_json(),
1915        };
1916        let session = match known_session {
1917            Some(id) => Some(id),
1918            None => envelope
1919                .session_id
1920                .map(|id| SessionId::new(id.into_owned()))
1921                .transpose()?,
1922        };
1923        let connection = connection.unwrap_or(shared.key);
1924        let event = RawEvent {
1925            connection,
1926            session,
1927            seq,
1928            method: match envelope.method {
1929                Some(std::borrow::Cow::Borrowed(text)) => MethodText::Shared(frame.text(text)?),
1930                Some(std::borrow::Cow::Owned(text)) => MethodText::Owned(text.into()),
1931                None => return Err(Error::new(ErrorKind::InvalidMessage)),
1932            },
1933            params,
1934            frame_len: frame.len(),
1935        };
1936        for (id, target) in targets {
1937            if !target.deliver(event.clone()) {
1938                let removed = shared.control().remove_subscription(id);
1939                drop(removed);
1940            }
1941        }
1942    }
1943    Ok(())
1944}
1945
1946#[cfg(test)]
1947mod tests {
1948    use super::*;
1949    use futures_util::{StreamExt, poll};
1950    use std::sync::atomic::AtomicUsize;
1951
1952    struct IdleReader(Arc<AtomicUsize>);
1953    struct IdleWriter(Arc<AtomicUsize>);
1954    struct IdleTransport(Arc<AtomicUsize>);
1955    impl Drop for IdleReader {
1956        fn drop(&mut self) {
1957            self.0.fetch_add(1, Ordering::SeqCst);
1958        }
1959    }
1960    impl Drop for IdleWriter {
1961        fn drop(&mut self) {
1962            self.0.fetch_add(1, Ordering::SeqCst);
1963        }
1964    }
1965    impl Transport for IdleTransport {
1966        type Reader = IdleReader;
1967        type Writer = IdleWriter;
1968        fn split(self) -> (Self::Reader, Self::Writer) {
1969            (IdleReader(self.0.clone()), IdleWriter(self.0))
1970        }
1971    }
1972    impl MessageReader for IdleReader {
1973        async fn recv(&mut self) -> std::result::Result<Option<Bytes>, TransportError> {
1974            std::future::pending().await
1975        }
1976    }
1977    impl MessageWriter for IdleWriter {
1978        async fn send(&mut self, _: Bytes) -> std::result::Result<(), TransportError> {
1979            Ok(())
1980        }
1981        async fn flush(&mut self) -> std::result::Result<(), TransportError> {
1982            Ok(())
1983        }
1984        async fn close(&mut self) -> std::result::Result<(), TransportError> {
1985            Ok(())
1986        }
1987    }
1988    #[derive(serde::Serialize, serde::Deserialize, Debug, PartialEq)]
1989    struct Payload {
1990        value: u32,
1991    }
1992    struct Echo;
1993    impl Command for Echo {
1994        type Params = Payload;
1995        type Response = Payload;
1996        const METHOD: &'static str = "Echo.echo";
1997    }
1998    struct Changed;
1999    impl Event for Changed {
2000        type Params = Payload;
2001        const METHOD: &'static str = "Echo.changed";
2002    }
2003    fn fixture(mut options: RuntimeOptions) -> (Connection, RawEventStream, Arc<AtomicUsize>) {
2004        options.close_timeout = Duration::ZERO;
2005        let drops = Arc::new(AtomicUsize::new(0));
2006        let (c, e) = Connection::from_transport(IdleTransport(drops.clone()), options).unwrap();
2007        (c, e, drops)
2008    }
2009    fn response(shared: &Arc<Shared>, id: i32, value: u32) {
2010        receive(
2011            shared,
2012            Bytes::from(format!("{{\"id\":{id},\"result\":{{\"value\":{value}}}}}")),
2013        )
2014        .unwrap();
2015    }
2016    async fn joined(c: &Connection) {
2017        let report = c.close().await;
2018        assert!(report.driver_resources_released);
2019        let task = lock(&c.lease.shared.task).take().unwrap();
2020        task.await.unwrap();
2021    }
2022
2023    async fn latest_receive_sequence_contract() {
2024        let (connection, mut events, _) = fixture(Default::default());
2025        assert_eq!(connection.latest_receive_seq(), None);
2026        let mut request = Box::pin(connection.root_session().send::<Echo>(Payload { value: 7 }));
2027        assert!(poll!(&mut request).is_pending());
2028        assert_eq!(connection.latest_receive_seq(), None);
2029        receive(
2030            &connection.lease.shared,
2031            Bytes::from_static(br#"{"method":"Echo.changed","params":{"value":1}}"#),
2032        )
2033        .unwrap();
2034        // 尚未消费的事件已经进入接收基线;出站命令不会推进它。
2035        assert_eq!(connection.latest_receive_seq().unwrap().get(), 1);
2036        response(
2037            &connection.lease.shared,
2038            request.request_id().unwrap().get(),
2039            7,
2040        );
2041        // 响应已经排队但原 Request 尚未 poll,基线仍必须包含该响应。
2042        assert_eq!(connection.latest_receive_seq().unwrap().get(), 2);
2043        assert_eq!(events.next().await.unwrap().unwrap().receive_seq().get(), 1);
2044        assert_eq!(connection.latest_receive_seq().unwrap().get(), 2);
2045        assert_eq!(request.await.unwrap().value, 7);
2046        // 无人等待的晚到响应也占一个合法接收序号。
2047        response(&connection.lease.shared, 12345, 8);
2048        assert_eq!(connection.latest_receive_seq().unwrap().get(), 3);
2049        assert!(receive(&connection.lease.shared, Bytes::from_static(b"null")).is_err());
2050        assert_eq!(connection.latest_receive_seq().unwrap().get(), 3);
2051        joined(&connection).await;
2052        assert_eq!(connection.latest_receive_seq().unwrap().get(), 3);
2053        receive(
2054            &connection.lease.shared,
2055            Bytes::from_static(br#"{"method":"Echo.changed"}"#),
2056        )
2057        .unwrap();
2058        assert_eq!(connection.latest_receive_seq().unwrap().get(), 3);
2059    }
2060
2061    #[tokio::test]
2062    async fn latest_receive_sequence_current_thread() {
2063        latest_receive_sequence_contract().await;
2064    }
2065
2066    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
2067    async fn latest_receive_sequence_multi_thread() {
2068        latest_receive_sequence_contract().await;
2069    }
2070
2071    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
2072    async fn latest_receive_sequence_concurrent_snapshot_and_exhaustion() {
2073        let (connection, events, _) = fixture(Default::default());
2074        let barrier = Arc::new(tokio::sync::Barrier::new(2));
2075        let observer = connection.clone();
2076        let observer_barrier = barrier.clone();
2077        let task = tokio::spawn(async move {
2078            for expected in 1..=32 {
2079                observer_barrier.wait().await;
2080                assert_eq!(observer.latest_receive_seq().unwrap().get(), expected);
2081                observer_barrier.wait().await;
2082            }
2083        });
2084        for _ in 1..=32 {
2085            receive(
2086                &connection.lease.shared,
2087                Bytes::from_static(br#"{"method":"Echo.changed"}"#),
2088            )
2089            .unwrap();
2090            barrier.wait().await;
2091            barrier.wait().await;
2092        }
2093        task.await.unwrap();
2094        connection.lease.shared.control().seq = u64::MAX - 1;
2095        receive(
2096            &connection.lease.shared,
2097            Bytes::from_static(br#"{"method":"Echo.changed"}"#),
2098        )
2099        .unwrap();
2100        assert_eq!(connection.latest_receive_seq().unwrap().get(), u64::MAX);
2101        let error = receive(
2102            &connection.lease.shared,
2103            Bytes::from_static(br#"{"method":"Echo.changed"}"#),
2104        )
2105        .unwrap_err();
2106        assert!(matches!(
2107            error.kind,
2108            ErrorKind::ResourceLimit {
2109                resource: "receive_seq"
2110            }
2111        ));
2112        assert_eq!(connection.latest_receive_seq().unwrap().get(), u64::MAX);
2113        connection.lease.shared.begin_close(error);
2114        joined(&connection).await;
2115        assert_eq!(connection.latest_receive_seq().unwrap().get(), u64::MAX);
2116        drop(events);
2117    }
2118
2119    #[tokio::test]
2120    async fn response_owner_survives_remove_and_receiver_drop() {
2121        let (c, events, drops) = fixture(Default::default());
2122        drop(events);
2123        let s = c.root_session();
2124        let shared = &c.lease.shared;
2125        let mut request = Box::pin(s.send::<Echo>(Payload { value: 1 }));
2126        assert!(poll!(&mut request).is_pending());
2127        let id = request.request_id().unwrap().get();
2128        let outbound = shared.pop().unwrap();
2129        response(shared, id, 7);
2130        assert!(shared.control().pending.is_empty());
2131        assert_eq!(shared.control().counts[0].requests, 1);
2132        assert!(shared.wire_budget.used() > 0);
2133        drop(request);
2134        assert_eq!(shared.control().counts[0].requests, 0);
2135        assert_eq!(shared.wire_budget.used(), 0);
2136        assert_eq!(shared.control().counts[0].slots, 1);
2137        drop(outbound);
2138        assert_eq!(shared.control().counts[0].slots, 0);
2139        joined(&c).await;
2140        assert_eq!(drops.load(Ordering::SeqCst), 2);
2141    }
2142    #[tokio::test(start_paused = true)]
2143    async fn queued_response_loses_to_deadline_and_fuses() {
2144        let (c, events, _) = fixture(Default::default());
2145        drop(events);
2146        let s = c.root_session();
2147        let mut request = Box::pin(s.send_with::<Echo>(
2148            Payload { value: 1 },
2149            RequestOptions {
2150                timeout: Timeout::After(Duration::from_secs(1)),
2151                ..Default::default()
2152            },
2153        ));
2154        assert!(poll!(&mut request).is_pending());
2155        response(&c.lease.shared, request.request_id().unwrap().get(), 2);
2156        tokio::time::advance(Duration::from_secs(1)).await;
2157        let error = request.as_mut().await.unwrap_err();
2158        assert!(matches!(error.kind, ErrorKind::Timeout));
2159        assert_eq!(error.context.unwrap().submission, Submission::PossiblySent);
2160        assert!(request.is_terminated());
2161        assert!(poll!(&mut request).is_pending());
2162        assert_eq!(c.lease.shared.control().counts[0].requests, 0);
2163        joined(&c).await;
2164    }
2165    #[tokio::test]
2166    async fn grants_reserve_capacity_without_polling_the_head() {
2167        let mut options = RuntimeOptions::default();
2168        options.limits.normal.requests = 2;
2169        options.limits.normal.outbound_slots = 2;
2170        options.limits.normal.admission_waiters = 3;
2171        let (c, events, _) = fixture(options);
2172        drop(events);
2173        let s = c.root_session();
2174        let shared = &c.lease.shared;
2175        let mut active1 = Box::pin(s.send::<Echo>(Payload { value: 1 }));
2176        let mut active2 = Box::pin(s.send::<Echo>(Payload { value: 2 }));
2177        assert!(poll!(&mut active1).is_pending());
2178        assert!(poll!(&mut active2).is_pending());
2179        let mut first = Box::pin(s.send::<Echo>(Payload { value: 3 }));
2180        let mut second = Box::pin(s.send::<Echo>(Payload { value: 4 }));
2181        let mut third = Box::pin(s.send::<Echo>(Payload { value: 5 }));
2182        assert!(poll!(&mut first).is_pending());
2183        assert!(poll!(&mut second).is_pending());
2184        assert!(poll!(&mut third).is_pending());
2185        let mut full = Box::pin(s.send::<Echo>(Payload { value: 6 }));
2186        assert!(matches!(
2187            poll!(&mut full),
2188            Poll::Ready(Err(Error {
2189                kind: ErrorKind::AdmissionFull,
2190                ..
2191            }))
2192        ));
2193        drop(active1);
2194        drop(active2);
2195        drop(shared.pop());
2196        drop(shared.pop());
2197        assert_eq!(
2198            shared
2199                .control()
2200                .waiters
2201                .values()
2202                .filter(|w| w.granted)
2203                .count(),
2204            2
2205        );
2206        assert!(poll!(&mut second).is_pending());
2207        let id = second.request_id().unwrap().get();
2208        response(shared, id, 4);
2209        assert_eq!(second.await.unwrap().value, 4);
2210        drop(shared.pop());
2211        assert!(shared.control().waiters.values().all(|w| w.granted));
2212        assert!(poll!(&mut third).is_pending());
2213        assert!(first.request_id().is_none());
2214        drop(first);
2215        drop(third);
2216        joined(&c).await;
2217    }
2218    #[tokio::test]
2219    async fn response_budget_failure_reaches_removed_sender() {
2220        let mut options = RuntimeOptions::default();
2221        options.limits.wire_bytes = 1;
2222        let (c, events, _) = fixture(options);
2223        drop(events);
2224        let mut request = Box::pin(c.root_session().send::<Echo>(Payload { value: 1 }));
2225        assert!(poll!(&mut request).is_pending());
2226        let error = receive(
2227            &c.lease.shared,
2228            Bytes::from(format!(
2229                "{{\"id\":{},\"result\":{{}}}}",
2230                request.request_id().unwrap().get()
2231            )),
2232        )
2233        .unwrap_err();
2234        assert!(matches!(error.kind, ErrorKind::ResourceLimit { .. }));
2235        c.lease.shared.begin_close(error);
2236        assert!(matches!(
2237            request.await.unwrap_err().kind,
2238            ErrorKind::ResourceLimit { .. }
2239        ));
2240        joined(&c).await;
2241    }
2242    #[tokio::test]
2243    async fn sessions_gate_retire_and_leave_published_frames() {
2244        let (c, events, _) = fixture(Default::default());
2245        drop(events);
2246        let id = SessionId::new("child".into()).unwrap();
2247        let child = c.adopt_session(id.clone()).unwrap();
2248        assert_eq!(child.key(), c.adopt_session(id.clone()).unwrap().key());
2249        let mut request = Box::pin(child.send::<Echo>(Payload { value: 1 }));
2250        assert!(poll!(&mut request).is_pending());
2251        child.close();
2252        assert!(matches!(
2253            request.await.unwrap_err().kind,
2254            ErrorKind::SessionClosed
2255        ));
2256        assert!(c.lease.shared.pop().is_some());
2257        assert!(matches!(
2258            c.adopt_session(id).err().unwrap().kind,
2259            ErrorKind::SessionIdRetired
2260        ));
2261        assert!(matches!(
2262            child
2263                .send::<Echo>(Payload { value: 1 })
2264                .await
2265                .unwrap_err()
2266                .kind,
2267            ErrorKind::SessionClosed
2268        ));
2269        assert!(!c.root_session().is_closed());
2270        joined(&c).await;
2271    }
2272    #[tokio::test]
2273    async fn overflow_terminal_has_priority_and_holds_subscription_slot() {
2274        let mut options = RuntimeOptions::default();
2275        options.initial_events.max_events = 1;
2276        options.limits.subscriptions = 2;
2277        let (c, mut all, _) = fixture(options);
2278        let mut typed = c
2279            .root_session()
2280            .events::<Changed>(Default::default())
2281            .unwrap();
2282        receive(
2283            &c.lease.shared,
2284            Bytes::from_static(br#"{"method":"Echo.changed","params":{"value":1}}"#),
2285        )
2286        .unwrap();
2287        receive(
2288            &c.lease.shared,
2289            Bytes::from_static(br#"{"method":"Echo.changed","params":{"value":2}}"#),
2290        )
2291        .unwrap();
2292        assert!(matches!(
2293            all.next().await.unwrap().unwrap_err().kind,
2294            ErrorKind::EventBufferFull
2295        ));
2296        assert!(all.next().await.is_none());
2297        assert!(c.raw_events(Default::default()).is_err());
2298        assert_eq!(typed.next().await.unwrap().unwrap().params.value, 1);
2299        assert_eq!(typed.next().await.unwrap().unwrap().params.value, 2);
2300        drop(all);
2301        assert!(c.raw_events(Default::default()).is_ok());
2302        joined(&c).await;
2303    }
2304    #[tokio::test]
2305    async fn typed_decode_terminates_only_its_own_stream() {
2306        let (c, mut all, _) = fixture(Default::default());
2307        let mut typed = c
2308            .root_session()
2309            .events::<Changed>(Default::default())
2310            .unwrap();
2311        receive(
2312            &c.lease.shared,
2313            Bytes::from_static(br#"{"method":"Echo.changed","params":{"value":"bad"}}"#),
2314        )
2315        .unwrap();
2316        assert!(matches!(
2317            typed.next().await.unwrap().unwrap_err().kind,
2318            ErrorKind::Decode
2319        ));
2320        assert!(typed.next().await.is_none());
2321        assert_eq!(all.next().await.unwrap().unwrap().connection_key(), c.key());
2322        assert_eq!(c.state(), ConnectionState::Open);
2323        joined(&c).await;
2324    }
2325    #[tokio::test]
2326    async fn last_lease_and_abort_release_transport_before_report() {
2327        let (c, events, drops) = fixture(Default::default());
2328        let shared = c.lease.shared.clone();
2329        let task = lock(&shared.task).take().unwrap();
2330        drop(events);
2331        drop(c);
2332        task.await.unwrap();
2333        assert_eq!(drops.load(Ordering::SeqCst), 2);
2334        assert_eq!(shared.control().state, ConnectionState::Closed);
2335        let (unpolled, unpolled_events, unpolled_drops) = fixture(Default::default());
2336        let task = lock(&unpolled.lease.shared.task).take().unwrap();
2337        task.abort();
2338        assert!(task.await.unwrap_err().is_cancelled());
2339        assert!(matches!(
2340            unpolled.closed().await.reason.kind,
2341            ErrorKind::DriverFailed
2342        ));
2343        assert_eq!(unpolled_drops.load(Ordering::SeqCst), 2);
2344        drop(unpolled_events);
2345        let (c, events, drops) = fixture(Default::default());
2346        tokio::task::yield_now().await;
2347        let task = lock(&c.lease.shared.task).take().unwrap();
2348        task.abort();
2349        assert!(task.await.unwrap_err().is_cancelled());
2350        let report = c.closed().await;
2351        assert!(matches!(report.reason.kind, ErrorKind::DriverFailed));
2352        assert_eq!(drops.load(Ordering::SeqCst), 2);
2353        drop(events);
2354    }
2355    #[tokio::test]
2356    async fn poisoned_control_converges_instead_of_reopening() {
2357        let (c, events, _) = fixture(Default::default());
2358        let shared = c.lease.shared.clone();
2359        let _ = std::panic::catch_unwind(|| {
2360            let _guard = shared.control.lock().unwrap();
2361            panic!("故障注入");
2362        });
2363        assert_eq!(c.state(), ConnectionState::Closing);
2364        let report = c.close().await;
2365        assert!(matches!(report.reason.kind, ErrorKind::DriverFailed));
2366        drop(events);
2367    }
2368    #[tokio::test]
2369    async fn id_sequence_exhaustion_keeps_existing_request() {
2370        let (c, events, _) = fixture(Default::default());
2371        drop(events);
2372        let shared = &c.lease.shared;
2373        shared.control().next_request = i64::from(i32::MAX);
2374        let mut last = Box::pin(c.root_session().send::<Echo>(Payload { value: 1 }));
2375        assert!(poll!(&mut last).is_pending());
2376        assert_eq!(last.request_id().unwrap().get(), i32::MAX);
2377        assert!(matches!(
2378            c.root_session()
2379                .send::<Echo>(Payload { value: 2 })
2380                .await
2381                .unwrap_err()
2382                .kind,
2383            ErrorKind::IdExhausted
2384        ));
2385        drop(last);
2386        shared.control().seq = u64::MAX;
2387        assert!(matches!(
2388            receive(shared, Bytes::from_static(br#"{"method":"Echo.changed"}"#))
2389                .unwrap_err()
2390                .kind,
2391            ErrorKind::ResourceLimit {
2392                resource: "receive_seq"
2393            }
2394        ));
2395        joined(&c).await;
2396    }
2397
2398    async fn response_session_mismatch_retirement_matrix() {
2399        let (c, events, _) = fixture(Default::default());
2400        drop(events);
2401        let child = c
2402            .adopt_session(SessionId::new("child".into()).unwrap())
2403            .unwrap();
2404
2405        // Driver 先读到迟到响应时,上层还来不及根据 detach 关闭 Session;只终结原请求。
2406        let mut request = Box::pin(child.send::<Echo>(Payload { value: 1 }));
2407        assert!(poll!(&mut request).is_pending());
2408        let request_id = request.request_id().unwrap();
2409        receive(
2410            &c.lease.shared,
2411            Bytes::from(format!(
2412                "{{\"id\":{},\"result\":{{\"value\":999}}}}",
2413                request_id.get()
2414            )),
2415        )
2416        .unwrap();
2417        let error = request.await.unwrap_err();
2418        assert!(matches!(error.kind, ErrorKind::ResponseSessionMismatch));
2419        let context = error.context.expect("错路由请求保留结构化上下文");
2420        assert_eq!(context.request_id, Some(request_id));
2421        assert_eq!(context.session_key, child.key());
2422        assert_eq!(context.submission, Submission::PossiblySent);
2423        assert_eq!(context.receive_seq, Some(ReceiveSeq(1)));
2424        assert_eq!(c.state(), ConnectionState::Open);
2425        assert!(c.lease.shared.control().pending.is_empty());
2426
2427        // 上层先处理 detach 时,Session::close 已移除 pending;更晚的未知响应同样不能破坏连接。
2428        let mut closing_request = Box::pin(child.send::<Echo>(Payload { value: 2 }));
2429        assert!(poll!(&mut closing_request).is_pending());
2430        let closing_id = closing_request.request_id().unwrap();
2431        child.close();
2432        let error = closing_request.await.unwrap_err();
2433        assert!(matches!(error.kind, ErrorKind::SessionClosed));
2434        receive(
2435            &c.lease.shared,
2436            Bytes::from(format!(
2437                "{{\"id\":{},\"result\":{{\"value\":2}}}}",
2438                closing_id.get()
2439            )),
2440        )
2441        .unwrap();
2442        assert_eq!(c.state(), ConnectionState::Open);
2443
2444        // 两种退役顺序之后,独立根路由仍可发送并接受严格匹配响应。
2445        let mut root = Box::pin(c.root_session().send::<Echo>(Payload { value: 3 }));
2446        assert!(poll!(&mut root).is_pending());
2447        let root_id = root.request_id().unwrap();
2448        receive(
2449            &c.lease.shared,
2450            Bytes::from(format!(
2451                "{{\"id\":{},\"result\":{{\"value\":3}}}}",
2452                root_id.get()
2453            )),
2454        )
2455        .unwrap();
2456        assert_eq!(root.await.unwrap(), Payload { value: 3 });
2457        joined(&c).await;
2458    }
2459
2460    #[tokio::test(flavor = "current_thread")]
2461    async fn response_session_mismatch_retirement_current_thread() {
2462        response_session_mismatch_retirement_matrix().await;
2463    }
2464
2465    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
2466    async fn response_session_mismatch_retirement_multi_thread() {
2467        response_session_mismatch_retirement_matrix().await;
2468    }
2469    #[derive(Default)]
2470    struct WriteLog {
2471        sent: Vec<Bytes>,
2472        flushes: Vec<(usize, usize)>,
2473        batch_frames: usize,
2474        batch_bytes: usize,
2475    }
2476    struct LoggedWriter {
2477        log: Arc<Mutex<WriteLog>>,
2478        flush_gate: Arc<tokio::sync::Semaphore>,
2479    }
2480    impl MessageWriter for LoggedWriter {
2481        async fn send(&mut self, bytes: Bytes) -> std::result::Result<(), TransportError> {
2482            let mut log = lock(&self.log);
2483            log.batch_frames += 1;
2484            log.batch_bytes += bytes.len();
2485            log.sent.push(bytes);
2486            Ok(())
2487        }
2488        async fn flush(&mut self) -> std::result::Result<(), TransportError> {
2489            {
2490                let mut log = lock(&self.log);
2491                let entry = (log.batch_frames, log.batch_bytes);
2492                log.flushes.push(entry);
2493                log.batch_frames = 0;
2494                log.batch_bytes = 0;
2495            }
2496            self.flush_gate.acquire().await.unwrap().forget();
2497            Ok(())
2498        }
2499        async fn close(&mut self) -> std::result::Result<(), TransportError> {
2500            Ok(())
2501        }
2502    }
2503    fn queue_raw(c: &Connection, size: usize, class: TrafficClass) -> Pin<Box<RawRequest>> {
2504        let params = RawJson::from_bytes(Bytes::from(format!(
2505            "{{\"text\":\"{}\"}}",
2506            "x".repeat(size)
2507        )))
2508        .unwrap();
2509        let mut request = Box::pin(c.root_session().send_raw(
2510            MethodName::new("Echo.raw".into()).unwrap(),
2511            params,
2512            RequestOptions {
2513                traffic_class: class,
2514                ..Default::default()
2515            },
2516        ));
2517        let mut cx = Context::from_waker(Waker::noop());
2518        assert!(request.as_mut().poll(&mut cx).is_pending());
2519        request
2520    }
2521    #[tokio::test]
2522    async fn writer_flush_owns_slots_and_obeys_frame_and_byte_limits() {
2523        let mut options = RuntimeOptions::default();
2524        options.limits.normal.outbound_slots = 64;
2525        let (c, events, _) = fixture(options);
2526        drop(events);
2527        let shared = c.lease.shared.clone();
2528        let requests = (0..33)
2529            .map(|_| queue_raw(&c, 1, TrafficClass::Normal))
2530            .collect::<Vec<_>>();
2531        let log = Arc::new(Mutex::new(WriteLog::default()));
2532        let gate = Arc::new(tokio::sync::Semaphore::new(0));
2533        let mut writer = LoggedWriter {
2534            log: log.clone(),
2535            flush_gate: gate.clone(),
2536        };
2537        {
2538            let mut batch = Vec::new();
2539            let mut writing = Box::pin(write_loop(&mut writer, &shared, &mut batch));
2540            assert!(poll!(&mut writing).is_pending());
2541            assert_eq!(lock(&log).flushes[0].0, 32);
2542            assert_eq!(shared.control().counts[0].slots, 33);
2543            gate.add_permits(1);
2544            assert!(poll!(&mut writing).is_pending());
2545            assert_eq!(lock(&log).flushes[1].0, 1);
2546            assert_eq!(shared.control().counts[0].slots, 1);
2547            gate.add_permits(1);
2548            assert!(poll!(&mut writing).is_pending());
2549            assert_eq!(shared.control().counts[0].slots, 0);
2550        }
2551        drop(requests);
2552        let requests = vec![
2553            queue_raw(&c, 40 << 10, TrafficClass::Normal),
2554            queue_raw(&c, 40 << 10, TrafficClass::Normal),
2555            queue_raw(&c, 70 << 10, TrafficClass::Normal),
2556            queue_raw(&c, 1, TrafficClass::Normal),
2557        ];
2558        *lock(&log) = WriteLog::default();
2559        {
2560            let mut batch = Vec::new();
2561            let mut writing = Box::pin(write_loop(&mut writer, &shared, &mut batch));
2562            for expected in 1..=4 {
2563                assert!(poll!(&mut writing).is_pending());
2564                let log = lock(&log);
2565                assert_eq!(log.flushes.len(), expected);
2566                assert_eq!(log.flushes[expected - 1].0, 1);
2567                assert_eq!(shared.control().counts[0].slots, 5 - expected);
2568                drop(log);
2569                gate.add_permits(1);
2570            }
2571            assert!(poll!(&mut writing).is_pending());
2572            assert_eq!(shared.control().counts[0].slots, 0);
2573        }
2574        drop(requests);
2575        joined(&c).await;
2576    }
2577    #[tokio::test]
2578    async fn control_capacity_is_independent_and_fair_eight_to_one() {
2579        let mut options = RuntimeOptions::default();
2580        options.limits.normal.requests = 2;
2581        options.limits.normal.outbound_slots = 2;
2582        options.limits.control.requests = 20;
2583        options.limits.control.outbound_slots = 20;
2584        let (c, events, _) = fixture(options);
2585        drop(events);
2586        let shared = &c.lease.shared;
2587        let mut requests = vec![
2588            queue_raw(&c, 1, TrafficClass::Normal),
2589            queue_raw(&c, 1, TrafficClass::Normal),
2590        ];
2591        requests.extend((0..17).map(|_| queue_raw(&c, 1, TrafficClass::Control)));
2592        let mut order = Vec::new();
2593        while let Some(frame) = shared.pop() {
2594            order.push(frame._permit.class);
2595            drop(frame);
2596        }
2597        assert_eq!(
2598            order,
2599            [vec![1; 8], vec![0], vec![1; 8], vec![0, 1]].concat()
2600        );
2601        assert_eq!(shared.control().counts[0].slots, 0);
2602        assert_eq!(shared.control().counts[1].slots, 0);
2603        drop(requests);
2604        joined(&c).await;
2605    }
2606    struct AlwaysReader {
2607        reads: Arc<AtomicUsize>,
2608    }
2609    impl MessageReader for AlwaysReader {
2610        async fn recv(&mut self) -> std::result::Result<Option<Bytes>, TransportError> {
2611            self.reads.fetch_add(1, Ordering::SeqCst);
2612            Ok(Some(Bytes::from_static(br#"{"id":1,"result":{}}"#)))
2613        }
2614    }
2615    #[tokio::test]
2616    async fn immediately_ready_read_and_write_loops_yield() {
2617        let mut options = RuntimeOptions::default();
2618        options.limits.normal.outbound_slots = 600;
2619        let (c, events, _) = fixture(options);
2620        drop(events);
2621        let shared = c.lease.shared.clone();
2622        let requests = (0..600)
2623            .map(|_| queue_raw(&c, 1, TrafficClass::Normal))
2624            .collect::<Vec<_>>();
2625        let log = Arc::new(Mutex::new(WriteLog::default()));
2626        let mut writer = LoggedWriter {
2627            log: log.clone(),
2628            flush_gate: Arc::new(tokio::sync::Semaphore::new(600)),
2629        };
2630        {
2631            let mut batch = Vec::new();
2632            let mut writing = Box::pin(write_loop(&mut writer, &shared, &mut batch));
2633            assert!(poll!(&mut writing).is_pending());
2634            let count = lock(&log).sent.len();
2635            assert!(count > 0 && count <= 256);
2636        }
2637        let reads = Arc::new(AtomicUsize::new(0));
2638        let mut reader = AlwaysReader {
2639            reads: reads.clone(),
2640        };
2641        {
2642            let mut reading = Box::pin(read_loop(&mut reader, &shared));
2643            assert!(poll!(&mut reading).is_pending());
2644            let count = reads.load(Ordering::SeqCst);
2645            assert!(count > 0 && count <= 256);
2646        }
2647        drop(requests);
2648        joined(&c).await;
2649    }
2650    #[tokio::test]
2651    async fn poisoned_subscription_converges_connection() {
2652        let (c, mut events, _) = fixture(Default::default());
2653        let subscriber = events.subscriber.clone();
2654        let _ = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
2655            let _guard = subscriber.state.lock().unwrap();
2656            panic!("订阅锁故障注入");
2657        }));
2658        let error = events.next().await.unwrap().unwrap_err();
2659        assert!(matches!(error.kind, ErrorKind::DriverFailed));
2660        assert_eq!(c.state(), ConnectionState::Closing);
2661        joined(&c).await;
2662    }
2663    struct PanicEncode;
2664    impl serde::Serialize for PanicEncode {
2665        fn serialize<S: serde::Serializer>(&self, _: S) -> std::result::Result<S::Ok, S::Error> {
2666            panic!("调用者编码故障注入")
2667        }
2668    }
2669    struct EncodeCommand;
2670    impl Command for EncodeCommand {
2671        type Params = PanicEncode;
2672        type Response = Payload;
2673        const METHOD: &'static str = "Echo.encode";
2674    }
2675    #[derive(Debug)]
2676    struct PanicDecode;
2677    impl<'de> serde::Deserialize<'de> for PanicDecode {
2678        fn deserialize<D: serde::Deserializer<'de>>(_: D) -> std::result::Result<Self, D::Error> {
2679            panic!("调用者解码故障注入")
2680        }
2681    }
2682    struct DecodeCommand;
2683    impl Command for DecodeCommand {
2684        type Params = Payload;
2685        type Response = PanicDecode;
2686        const METHOD: &'static str = "Echo.decode";
2687    }
2688    async fn user_panics_cleanup_case() {
2689        let (c, events, _) = fixture(Default::default());
2690        drop(events);
2691        let shared = c.lease.shared.clone();
2692        let mut cx = Context::from_waker(Waker::noop());
2693        let mut encode = Box::pin(c.root_session().send::<EncodeCommand>(PanicEncode));
2694        assert!(
2695            std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| encode
2696                .as_mut()
2697                .poll(&mut cx)))
2698            .is_err()
2699        );
2700        drop(encode);
2701        assert_eq!(shared.control().counts[0].requests, 0);
2702        assert_eq!(shared.control().counts[0].slots, 0);
2703        assert_eq!(shared.control().counts[0].bytes, 0);
2704        let mut decode = Box::pin(c.root_session().send::<DecodeCommand>(Payload { value: 1 }));
2705        assert!(decode.as_mut().poll(&mut cx).is_pending());
2706        response(&shared, decode.request_id().unwrap().get(), 2);
2707        assert!(
2708            std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| decode
2709                .as_mut()
2710                .poll(&mut cx)))
2711            .is_err()
2712        );
2713        drop(decode);
2714        assert_eq!(shared.control().counts[0].requests, 0);
2715        assert_eq!(shared.wire_budget.used(), 0);
2716        assert_eq!(c.state(), ConnectionState::Open);
2717        joined(&c).await;
2718    }
2719    #[tokio::test]
2720    async fn user_panics_cleanup_current_thread() {
2721        user_panics_cleanup_case().await;
2722    }
2723    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
2724    async fn user_panics_cleanup_multi_thread() {
2725        user_panics_cleanup_case().await;
2726    }
2727    #[tokio::test(start_paused = true)]
2728    async fn dropping_close_waiter_does_not_cancel_shared_shutdown() {
2729        let (c, events, drops) = fixture(Default::default());
2730        let other = c.clone();
2731        let mut close = Box::pin(c.close());
2732        assert!(poll!(&mut close).is_pending());
2733        drop(close);
2734        let report = other.closed().await;
2735        assert!(report.driver_resources_released);
2736        assert_eq!(drops.load(Ordering::SeqCst), 2);
2737        assert_eq!(c.close().await.transport_end, report.transport_end);
2738        let task = lock(&c.lease.shared.task).take().unwrap();
2739        task.await.unwrap();
2740        drop(events);
2741    }
2742    #[tokio::test]
2743    async fn invalid_runtime_limits_reject_before_driver() {
2744        for options in [
2745            RuntimeOptions {
2746                initial_events: SubscriptionOptions {
2747                    max_events: 0,
2748                    max_bytes: 1,
2749                },
2750                ..Default::default()
2751            },
2752            RuntimeOptions {
2753                limits: Limits {
2754                    max_json_depth: 129,
2755                    ..Default::default()
2756                },
2757                ..Default::default()
2758            },
2759        ] {
2760            assert!(validate_options(&options).is_err());
2761        }
2762        assert_eq!(TrafficClass::Normal.index(), 0);
2763        assert_eq!(TrafficClass::Control.index(), 1);
2764    }
2765    struct EncodingBarrier {
2766        entered: Arc<std::sync::Barrier>,
2767        resume: Arc<std::sync::Barrier>,
2768    }
2769    impl serde::Serialize for EncodingBarrier {
2770        fn serialize<S: serde::Serializer>(
2771            &self,
2772            serializer: S,
2773        ) -> std::result::Result<S::Ok, S::Error> {
2774            self.entered.wait();
2775            self.resume.wait();
2776            Payload { value: 1 }.serialize(serializer)
2777        }
2778    }
2779    struct BarrierCommand;
2780    impl Command for BarrierCommand {
2781        type Params = EncodingBarrier;
2782        type Response = Payload;
2783        const METHOD: &'static str = "Echo.barrier";
2784    }
2785    async fn close_during_encoding_case() {
2786        for close_connection in [false, true] {
2787            let (c, events, _) = fixture(Default::default());
2788            drop(events);
2789            let child = c
2790                .adopt_session(SessionId::new("child".into()).unwrap())
2791                .unwrap();
2792            let entered = Arc::new(std::sync::Barrier::new(2));
2793            let resume = Arc::new(std::sync::Barrier::new(2));
2794            let closer = if close_connection {
2795                c.root_session()
2796            } else {
2797                child.clone()
2798            };
2799            let other_entered = entered.clone();
2800            let other_resume = resume.clone();
2801            let thread = std::thread::spawn(move || {
2802                other_entered.wait();
2803                closer.close();
2804                other_resume.wait();
2805            });
2806            let mut request =
2807                Box::pin(child.send::<BarrierCommand>(EncodingBarrier { entered, resume }));
2808            let result = request.as_mut().await.unwrap_err();
2809            thread.join().unwrap();
2810            assert_eq!(request.submission(), Submission::NotSubmitted);
2811            assert!(matches!(
2812                result.kind,
2813                ErrorKind::ConnectionClosed | ErrorKind::SessionClosed
2814            ));
2815            assert!(c.lease.shared.control().pending.is_empty());
2816            assert!(
2817                c.lease
2818                    .shared
2819                    .control()
2820                    .queues
2821                    .iter()
2822                    .all(VecDeque::is_empty)
2823            );
2824            assert_eq!(c.lease.shared.control().counts[0].requests, 0);
2825            assert_eq!(c.lease.shared.control().counts[0].slots, 0);
2826            assert_eq!(c.lease.shared.control().counts[0].bytes, 0);
2827            joined(&c).await;
2828        }
2829    }
2830    #[tokio::test]
2831    async fn close_during_encoding_current_thread() {
2832        close_during_encoding_case().await;
2833    }
2834    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
2835    async fn close_during_encoding_multi_thread() {
2836        close_during_encoding_case().await;
2837    }
2838    #[tokio::test(start_paused = true)]
2839    async fn granted_waiter_timeout_returns_both_permits_and_advances_fifo() {
2840        let mut options = RuntimeOptions::default();
2841        options.limits.normal.requests = 1;
2842        options.limits.normal.outbound_slots = 1;
2843        let (c, events, _) = fixture(options);
2844        drop(events);
2845        let mut first = queue_raw(&c, 1, TrafficClass::Normal);
2846        let mut expiring = Box::pin(c.root_session().send_with::<Echo>(
2847            Payload { value: 2 },
2848            RequestOptions {
2849                timeout: Timeout::After(Duration::from_secs(1)),
2850                ..Default::default()
2851            },
2852        ));
2853        assert!(poll!(&mut expiring).is_pending());
2854        let mut next = Box::pin(c.root_session().send::<Echo>(Payload { value: 3 }));
2855        assert!(poll!(&mut next).is_pending());
2856        response(&c.lease.shared, first.request_id().unwrap().get(), 1);
2857        assert!(first.as_mut().await.is_ok());
2858        drop(c.lease.shared.pop());
2859        assert_eq!(
2860            c.lease
2861                .shared
2862                .control()
2863                .waiters
2864                .values()
2865                .filter(|w| w.granted)
2866                .count(),
2867            1
2868        );
2869        tokio::time::advance(Duration::from_secs(1)).await;
2870        assert!(matches!(
2871            expiring.await.unwrap_err().kind,
2872            ErrorKind::Timeout
2873        ));
2874        assert!(poll!(&mut next).is_pending());
2875        assert!(next.request_id().is_some());
2876        drop(next);
2877        joined(&c).await;
2878    }
2879    #[derive(Clone, Copy)]
2880    enum CloseMode {
2881        Fail,
2882        Pending,
2883    }
2884    struct CloseState {
2885        closing: std::sync::atomic::AtomicBool,
2886        notify: Notify,
2887        observed: Notify,
2888        drops: AtomicUsize,
2889    }
2890    struct CloseReader {
2891        state: Arc<CloseState>,
2892        mode: CloseMode,
2893    }
2894    struct CloseWriter {
2895        state: Arc<CloseState>,
2896        mode: CloseMode,
2897    }
2898    struct CloseTransport {
2899        state: Arc<CloseState>,
2900        read: CloseMode,
2901        write: CloseMode,
2902    }
2903    impl Transport for CloseTransport {
2904        type Reader = CloseReader;
2905        type Writer = CloseWriter;
2906        fn split(self) -> (Self::Reader, Self::Writer) {
2907            (
2908                CloseReader {
2909                    state: self.state.clone(),
2910                    mode: self.read,
2911                },
2912                CloseWriter {
2913                    state: self.state,
2914                    mode: self.write,
2915                },
2916            )
2917        }
2918    }
2919    impl Drop for CloseReader {
2920        fn drop(&mut self) {
2921            self.state.drops.fetch_add(1, Ordering::SeqCst);
2922        }
2923    }
2924    impl Drop for CloseWriter {
2925        fn drop(&mut self) {
2926            self.state.drops.fetch_add(1, Ordering::SeqCst);
2927        }
2928    }
2929    impl MessageReader for CloseReader {
2930        async fn recv(&mut self) -> std::result::Result<Option<Bytes>, TransportError> {
2931            let notification = self.state.notify.notified();
2932            tokio::pin!(notification);
2933            notification.as_mut().enable();
2934            if !self.state.closing.load(Ordering::SeqCst) {
2935                notification.await;
2936            }
2937            match self.mode {
2938                CloseMode::Fail => {
2939                    self.state.observed.notify_one();
2940                    Err(TransportError::new(io::Error::other("关闭读故障")))
2941                }
2942                CloseMode::Pending => std::future::pending().await,
2943            }
2944        }
2945    }
2946    impl MessageWriter for CloseWriter {
2947        async fn send(&mut self, _: Bytes) -> std::result::Result<(), TransportError> {
2948            Ok(())
2949        }
2950        async fn flush(&mut self) -> std::result::Result<(), TransportError> {
2951            Ok(())
2952        }
2953        async fn close(&mut self) -> std::result::Result<(), TransportError> {
2954            self.state.closing.store(true, Ordering::SeqCst);
2955            self.state.notify.notify_waiters();
2956            match self.mode {
2957                CloseMode::Fail => {
2958                    self.state.observed.notify_one();
2959                    Err(TransportError::new(io::Error::other("关闭写故障")))
2960                }
2961                CloseMode::Pending => std::future::pending().await,
2962            }
2963        }
2964    }
2965    #[tokio::test(start_paused = true)]
2966    async fn shutdown_keeps_observed_error_while_other_direction_times_out() {
2967        for (read, write) in [
2968            (CloseMode::Fail, CloseMode::Pending),
2969            (CloseMode::Pending, CloseMode::Fail),
2970        ] {
2971            let state = Arc::new(CloseState {
2972                closing: std::sync::atomic::AtomicBool::new(false),
2973                notify: Notify::new(),
2974                observed: Notify::new(),
2975                drops: AtomicUsize::new(0),
2976            });
2977            let (c, events) = Connection::from_transport(
2978                CloseTransport {
2979                    state: state.clone(),
2980                    read,
2981                    write,
2982                },
2983                RuntimeOptions {
2984                    close_timeout: Duration::from_secs(5),
2985                    ..Default::default()
2986                },
2987            )
2988            .unwrap();
2989            let mut closing = Box::pin(c.close());
2990            assert!(poll!(&mut closing).is_pending());
2991            state.observed.notified().await;
2992            assert_eq!(c.lease.shared.control().supplemental_errors.len(), 1);
2993            assert!(poll!(&mut closing).is_pending());
2994            tokio::time::advance(Duration::from_secs(5)).await;
2995            let report = closing.await;
2996            assert!(matches!(report.reason.kind, ErrorKind::ConnectionClosed));
2997            assert_eq!(report.transport_end, TransportEnd::Aborted);
2998            assert_eq!(report.supplemental_errors.len(), 1);
2999            assert!(matches!(
3000                report.supplemental_errors[0].kind,
3001                ErrorKind::Transport
3002            ));
3003            assert!(std::error::Error::source(&report.supplemental_errors[0]).is_some());
3004            assert_eq!(state.drops.load(Ordering::SeqCst), 2);
3005            let task = lock(&c.lease.shared.task).take().unwrap();
3006            task.await.unwrap();
3007            drop(events);
3008        }
3009    }
3010    #[tokio::test(start_paused = true)]
3011    async fn both_shutdown_failures_are_bounded_and_preserve_first_reason() {
3012        let state = Arc::new(CloseState {
3013            closing: std::sync::atomic::AtomicBool::new(false),
3014            notify: Notify::new(),
3015            observed: Notify::new(),
3016            drops: AtomicUsize::new(0),
3017        });
3018        let (c, events) = Connection::from_transport(
3019            CloseTransport {
3020                state: state.clone(),
3021                read: CloseMode::Fail,
3022                write: CloseMode::Fail,
3023            },
3024            Default::default(),
3025        )
3026        .unwrap();
3027        let report = c.close().await;
3028        assert!(matches!(report.reason.kind, ErrorKind::ConnectionClosed));
3029        assert_eq!(report.transport_end, TransportEnd::Failed);
3030        assert_eq!(report.supplemental_errors.len(), 2);
3031        assert!(
3032            report
3033                .supplemental_errors
3034                .iter()
3035                .all(|error| matches!(error.kind, ErrorKind::Transport))
3036        );
3037        assert_eq!(state.drops.load(Ordering::SeqCst), 2);
3038        assert_eq!(c.close().await.supplemental_errors.len(), 2);
3039        let task = lock(&c.lease.shared.task).take().unwrap();
3040        task.await.unwrap();
3041        drop(events);
3042    }
3043    #[tokio::test]
3044    async fn interrupted_writer_keeps_batch_permits_until_transport_is_dropped() {
3045        let (c, events, _) = fixture(Default::default());
3046        drop(events);
3047        let request = queue_raw(&c, 100, TrafficClass::Normal);
3048        let shared = c.lease.shared.clone();
3049        let log = Arc::new(Mutex::new(WriteLog::default()));
3050        let mut writer = LoggedWriter {
3051            log,
3052            flush_gate: Arc::new(tokio::sync::Semaphore::new(0)),
3053        };
3054        let mut batch = Vec::new();
3055        {
3056            let mut writing = Box::pin(write_loop(&mut writer, &shared, &mut batch));
3057            assert!(poll!(&mut writing).is_pending());
3058        }
3059        assert_eq!(shared.control().counts[0].slots, 1);
3060        assert!(shared.control().counts[0].bytes > 0);
3061        assert_eq!(batch.len(), 1);
3062        drop(writer);
3063        batch.clear();
3064        assert_eq!(shared.control().counts[0].slots, 0);
3065        assert_eq!(shared.control().counts[0].bytes, 0);
3066        drop(request);
3067        joined(&c).await;
3068    }
3069    #[tokio::test]
3070    async fn typed_decode_failure_removes_exact_subscription_index() {
3071        let (c, events, _) = fixture(Default::default());
3072        drop(events);
3073        let session = c.root_session();
3074        for _ in 0..100 {
3075            let mut typed = session.events::<Changed>(Default::default()).unwrap();
3076            receive(
3077                &c.lease.shared,
3078                Bytes::from_static(br#"{"method":"Echo.changed","params":{"value":"bad"}}"#),
3079            )
3080            .unwrap();
3081            assert!(typed.next().await.unwrap().is_err());
3082            drop(typed);
3083            assert!(c.lease.shared.control().exact.is_empty());
3084        }
3085        joined(&c).await;
3086    }
3087    struct PartialState {
3088        shared: Mutex<Option<Weak<Shared>>>,
3089        entered: Notify,
3090        dropped_slots: AtomicUsize,
3091    }
3092    struct PartialWriter(Arc<PartialState>);
3093    struct PartialTransport(Arc<PartialState>);
3094    impl Drop for PartialWriter {
3095        fn drop(&mut self) {
3096            if let Some(shared) = lock(&self.0.shared).as_ref().and_then(Weak::upgrade) {
3097                self.0
3098                    .dropped_slots
3099                    .store(shared.control().counts[0].slots, Ordering::SeqCst);
3100            }
3101        }
3102    }
3103    impl Transport for PartialTransport {
3104        type Reader = IdleReader;
3105        type Writer = PartialWriter;
3106        fn split(self) -> (Self::Reader, Self::Writer) {
3107            (
3108                IdleReader(Arc::new(AtomicUsize::new(0))),
3109                PartialWriter(self.0),
3110            )
3111        }
3112    }
3113    impl MessageWriter for PartialWriter {
3114        async fn send(&mut self, _: Bytes) -> std::result::Result<(), TransportError> {
3115            self.0.entered.notify_one();
3116            std::future::pending().await
3117        }
3118        async fn flush(&mut self) -> std::result::Result<(), TransportError> {
3119            std::future::pending().await
3120        }
3121        async fn close(&mut self) -> std::result::Result<(), TransportError> {
3122            std::future::pending().await
3123        }
3124    }
3125    #[tokio::test(start_paused = true)]
3126    async fn driver_shutdown_drops_transport_before_inflight_send_permit() {
3127        let state = Arc::new(PartialState {
3128            shared: Mutex::new(None),
3129            entered: Notify::new(),
3130            dropped_slots: AtomicUsize::new(0),
3131        });
3132        let (c, events) = Connection::from_transport(
3133            PartialTransport(state.clone()),
3134            RuntimeOptions {
3135                close_timeout: Duration::from_secs(5),
3136                ..Default::default()
3137            },
3138        )
3139        .unwrap();
3140        *lock(&state.shared) = Some(Arc::downgrade(&c.lease.shared));
3141        let request = queue_raw(&c, 1, TrafficClass::Normal);
3142        state.entered.notified().await;
3143        let child = c
3144            .adopt_session(SessionId::new("retired".into()).unwrap())
3145            .unwrap();
3146        child.close();
3147        let mut close = Box::pin(c.close());
3148        assert!(poll!(&mut close).is_pending());
3149        assert_eq!(c.lease.shared.control().counts[0].slots, 1);
3150        tokio::time::advance(Duration::from_secs(5)).await;
3151        let report = close.await;
3152        assert!(report.driver_resources_released);
3153        assert_eq!(state.dropped_slots.load(Ordering::SeqCst), 1);
3154        assert_eq!(c.lease.shared.control().counts[0].slots, 0);
3155        assert!(c.lease.shared.control().routes.is_empty());
3156        assert!(c.lease.shared.control().retired.is_empty());
3157        let task = lock(&c.lease.shared.task).take().unwrap();
3158        task.await.unwrap();
3159        drop(request);
3160        drop(events);
3161    }
3162    #[tokio::test]
3163    async fn protocol_errors_without_data_keep_queued_frame_budget() {
3164        for (count, message_len) in [(1, 512 << 10), (32, 8 << 10)] {
3165            let (c, events, _) = fixture(Default::default());
3166            drop(events);
3167            let shared = &c.lease.shared;
3168            let mut requests = Vec::new();
3169            let mut sizes = Vec::new();
3170            let mut expected = 0;
3171            for _ in 0..count {
3172                let mut request = Box::pin(c.root_session().send::<Echo>(Payload { value: 1 }));
3173                assert!(poll!(&mut request).is_pending());
3174                let id = request.request_id().unwrap().get();
3175                let bytes = Bytes::from(format!(
3176                    "{{\"id\":{id},\"error\":{{\"code\":-1,\"message\":\"{}\"}}}}",
3177                    "x".repeat(message_len)
3178                ));
3179                let len = bytes.len();
3180                receive(shared, bytes).unwrap();
3181                expected += len;
3182                assert_eq!(shared.wire_budget.used(), expected);
3183                requests.push(request);
3184                sizes.push(len);
3185            }
3186            assert!(shared.control().pending.is_empty());
3187            assert_eq!(shared.control().counts[0].requests, count);
3188            while let Some(request) = requests.pop() {
3189                drop(request);
3190                expected -= sizes.pop().unwrap();
3191                assert_eq!(shared.wire_budget.used(), expected);
3192            }
3193            assert_eq!(shared.control().counts[0].requests, 0);
3194            joined(&c).await;
3195        }
3196    }
3197    #[tokio::test]
3198    async fn delivered_protocol_error_clones_share_one_frame_permit() {
3199        let (c, events, _) = fixture(Default::default());
3200        drop(events);
3201        let shared = &c.lease.shared;
3202        let mut request = Box::pin(c.root_session().send::<Echo>(Payload { value: 1 }));
3203        assert!(poll!(&mut request).is_pending());
3204        let bytes = Bytes::from(format!(
3205            "{{\"id\":{},\"error\":{{\"code\":-1,\"message\":\"{}\"}}}}",
3206            request.request_id().unwrap().get(),
3207            "x".repeat(64 << 10)
3208        ));
3209        let len = bytes.len();
3210        receive(shared, bytes).unwrap();
3211        let error = request.await.unwrap_err();
3212        assert!(matches!(error.kind, ErrorKind::Protocol { data: None, .. }));
3213        assert_eq!(shared.wire_budget.used(), len);
3214        let cloned = error.clone();
3215        drop(error);
3216        assert_eq!(shared.wire_budget.used(), len);
3217        drop(cloned);
3218        assert_eq!(shared.wire_budget.used(), 0);
3219        joined(&c).await;
3220    }
3221    #[tokio::test]
3222    async fn retained_protocol_error_exhausts_wire_budget() {
3223        let mut options = RuntimeOptions::default();
3224        options.limits.wire_bytes = 100 << 10;
3225        let (c, events, _) = fixture(options);
3226        drop(events);
3227        let shared = &c.lease.shared;
3228        let mut first = Box::pin(c.root_session().send::<Echo>(Payload { value: 1 }));
3229        let mut second = Box::pin(c.root_session().send::<Echo>(Payload { value: 2 }));
3230        assert!(poll!(&mut first).is_pending());
3231        assert!(poll!(&mut second).is_pending());
3232        for (index, request) in [&first, &second].into_iter().enumerate() {
3233            let bytes = Bytes::from(format!(
3234                "{{\"id\":{},\"error\":{{\"code\":-1,\"message\":\"{}\"}}}}",
3235                request.request_id().unwrap().get(),
3236                "x".repeat(64 << 10)
3237            ));
3238            let result = receive(shared, bytes);
3239            if index == 0 {
3240                assert!(result.is_ok());
3241            } else {
3242                assert!(matches!(
3243                    result.unwrap_err().kind,
3244                    ErrorKind::ResourceLimit { .. }
3245                ));
3246            }
3247        }
3248        assert!(shared.wire_budget.used() > 64 << 10);
3249        assert!(matches!(
3250            second.await.unwrap_err().kind,
3251            ErrorKind::ResourceLimit { .. }
3252        ));
3253        drop(first);
3254        assert_eq!(shared.wire_budget.used(), 0);
3255        joined(&c).await;
3256    }
3257    struct StressReader(tokio::sync::mpsc::Receiver<Bytes>);
3258    struct StressWriter(Option<tokio::sync::mpsc::Sender<Bytes>>);
3259    struct StressTransport {
3260        input: tokio::sync::mpsc::Receiver<Bytes>,
3261        output: tokio::sync::mpsc::Sender<Bytes>,
3262    }
3263    impl Transport for StressTransport {
3264        type Reader = StressReader;
3265        type Writer = StressWriter;
3266        fn split(self) -> (Self::Reader, Self::Writer) {
3267            (StressReader(self.input), StressWriter(Some(self.output)))
3268        }
3269    }
3270    impl MessageReader for StressReader {
3271        async fn recv(&mut self) -> std::result::Result<Option<Bytes>, TransportError> {
3272            Ok(self.0.recv().await)
3273        }
3274    }
3275    impl MessageWriter for StressWriter {
3276        async fn send(&mut self, bytes: Bytes) -> std::result::Result<(), TransportError> {
3277            self.0
3278                .as_ref()
3279                .unwrap()
3280                .send(bytes)
3281                .await
3282                .map_err(|error| TransportError::new(io::Error::other(error)))
3283        }
3284        async fn flush(&mut self) -> std::result::Result<(), TransportError> {
3285            Ok(())
3286        }
3287        async fn close(&mut self) -> std::result::Result<(), TransportError> {
3288            self.0.take();
3289            Ok(())
3290        }
3291    }
3292    #[derive(serde::Deserialize)]
3293    struct StressCommand {
3294        id: i32,
3295        params: Payload,
3296        #[serde(rename = "sessionId")]
3297        session_id: Option<String>,
3298    }
3299
3300    struct StressReport {
3301        iterations: usize,
3302        cancelled: usize,
3303        subscriptions: usize,
3304        elapsed: Duration,
3305        initial_rss_bytes: Option<u64>,
3306        peak_rss_bytes: Option<u64>,
3307        final_rss_bytes: Option<u64>,
3308    }
3309
3310    #[cfg(target_os = "linux")]
3311    fn current_rss_bytes() -> Option<u64> {
3312        let status = std::fs::read_to_string("/proc/self/status").ok()?;
3313        let kib = status.lines().find_map(|line| {
3314            let value = line.strip_prefix("VmRSS:")?.split_whitespace().next()?;
3315            value.parse::<u64>().ok()
3316        })?;
3317        kib.checked_mul(1024)
3318    }
3319
3320    #[cfg(not(target_os = "linux"))]
3321    fn current_rss_bytes() -> Option<u64> {
3322        None
3323    }
3324
3325    fn assert_stress_quiescent(shared: &Shared, active_routes: usize) {
3326        let control = shared.control();
3327        assert!(control.pending.is_empty());
3328        assert!(control.waiters.is_empty());
3329        assert!(control.queues.iter().all(VecDeque::is_empty));
3330        assert!(control.counts.iter().all(|counts| {
3331            counts.requests == 0 && counts.slots == 0 && counts.bytes == 0 && counts.waiters == 0
3332        }));
3333        assert_eq!(control.subscription_count, 0);
3334        assert!(control.subscriptions.is_empty());
3335        assert!(control.all.is_empty());
3336        assert!(control.wild.is_empty());
3337        assert!(control.exact.is_empty());
3338        assert_eq!(control.routes.len(), active_routes);
3339        assert_eq!(shared.wire_budget.used(), 0);
3340    }
3341
3342    async fn mixed_lifecycle_stress(
3343        minimum_iterations: usize,
3344        minimum_duration: Duration,
3345    ) -> StressReport {
3346        let started = std::time::Instant::now();
3347        let initial_rss_bytes = current_rss_bytes();
3348        let mut peak_rss_bytes = initial_rss_bytes;
3349        let (out_tx, mut out_rx) = tokio::sync::mpsc::channel::<Bytes>(4);
3350        let (in_tx, in_rx) = tokio::sync::mpsc::channel::<Bytes>(4);
3351        let (cancel_seen_tx, mut cancel_seen_rx) = tokio::sync::mpsc::channel::<()>(1);
3352        let (cancel_release_tx, mut cancel_release_rx) = tokio::sync::mpsc::channel::<()>(1);
3353        let endpoint = tokio::spawn(async move {
3354            let mut count = 0usize;
3355            while let Some(bytes) = out_rx.recv().await {
3356                let command: StressCommand = serde_json::from_slice(&bytes).unwrap();
3357                let route = command
3358                    .session_id
3359                    .map(|id| format!(",\"sessionId\":{}", serde_json::to_string(&id).unwrap()))
3360                    .unwrap_or_default();
3361                let value = command.params.value;
3362                if value % 4 == 1 {
3363                    cancel_seen_tx.send(()).await.unwrap();
3364                    cancel_release_rx.recv().await.unwrap();
3365                }
3366                in_tx
3367                    .send(Bytes::from(format!(
3368                        "{{\"method\":\"Echo.changed\",\"params\":{{\"value\":{value}}}{route}}}"
3369                    )))
3370                    .await
3371                    .unwrap();
3372                in_tx
3373                    .send(Bytes::from(format!(
3374                        "{{\"id\":{},\"result\":{{\"value\":{value}}}{route}}}",
3375                        command.id
3376                    )))
3377                    .await
3378                    .unwrap();
3379                count += 1;
3380            }
3381            count
3382        });
3383        let (connection, events) = Connection::from_transport(
3384            StressTransport {
3385                input: in_rx,
3386                output: out_tx,
3387            },
3388            Default::default(),
3389        )
3390        .unwrap();
3391        drop(events);
3392        let shared = connection.lease.shared.clone();
3393        let sessions = [
3394            connection.root_session(),
3395            connection
3396                .adopt_session(SessionId::new("stress-a".into()).unwrap())
3397                .unwrap(),
3398            connection
3399                .adopt_session(SessionId::new("stress-b".into()).unwrap())
3400                .unwrap(),
3401            connection
3402                .adopt_session(SessionId::new("stress-c".into()).unwrap())
3403                .unwrap(),
3404        ];
3405        let mut iterations = 0usize;
3406        let mut cancelled = 0usize;
3407        let mut subscriptions = 0usize;
3408        while iterations < minimum_iterations || started.elapsed() < minimum_duration {
3409            let session = &sessions[iterations % sessions.len()];
3410            let value = u32::try_from(iterations % u32::MAX as usize).unwrap();
3411            match iterations % 4 {
3412                0 => assert_eq!(
3413                    session.send::<Echo>(Payload { value }).await.unwrap().value,
3414                    value
3415                ),
3416                1 => {
3417                    let mut request = Box::pin(session.send::<Echo>(Payload { value }));
3418                    assert!(poll!(&mut request).is_pending());
3419                    cancel_seen_rx.recv().await.unwrap();
3420                    assert_eq!(request.submission(), Submission::PossiblySent);
3421                    drop(request);
3422                    cancel_release_tx.send(()).await.unwrap();
3423                    cancelled += 1;
3424                }
3425                2 => {
3426                    let mut events = session.events::<Changed>(Default::default()).unwrap();
3427                    assert_eq!(
3428                        session.send::<Echo>(Payload { value }).await.unwrap().value,
3429                        value
3430                    );
3431                    assert_eq!(events.next().await.unwrap().unwrap().params.value, value);
3432                    drop(events);
3433                    subscriptions += 1;
3434                }
3435                _ => {
3436                    drop(session.raw_events(Default::default()).unwrap());
3437                    assert_eq!(
3438                        session.send::<Echo>(Payload { value }).await.unwrap().value,
3439                        value
3440                    );
3441                    subscriptions += 1;
3442                }
3443            }
3444            iterations += 1;
3445            if iterations.is_multiple_of(4096) {
3446                assert_stress_quiescent(&shared, 3);
3447                if let Some(rss) = current_rss_bytes() {
3448                    peak_rss_bytes = Some(peak_rss_bytes.unwrap_or(rss).max(rss));
3449                }
3450            }
3451        }
3452        assert_stress_quiescent(&shared, 3);
3453        for session in sessions.iter().skip(1) {
3454            session.close();
3455        }
3456        assert_eq!(shared.control().retired.len(), 3);
3457        joined(&connection).await;
3458        assert_eq!(endpoint.await.unwrap(), iterations);
3459        assert!(shared.control().routes.is_empty());
3460        assert!(shared.control().retired.is_empty());
3461        assert_eq!(shared.wire_budget.used(), 0);
3462        let final_rss_bytes = current_rss_bytes();
3463        if let Some(rss) = final_rss_bytes {
3464            peak_rss_bytes = Some(peak_rss_bytes.unwrap_or(rss).max(rss));
3465        }
3466        StressReport {
3467            iterations,
3468            cancelled,
3469            subscriptions,
3470            elapsed: started.elapsed(),
3471            initial_rss_bytes,
3472            peak_rss_bytes,
3473            final_rss_bytes,
3474        }
3475    }
3476
3477    fn print_stress_report(kind: &str, report: &StressReport) {
3478        println!(
3479            "YDP_STRESS_REPORT={}",
3480            serde_json::json!({
3481                "kind": kind,
3482                "iterations": report.iterations,
3483                "cancelled": report.cancelled,
3484                "subscriptions": report.subscriptions,
3485                "elapsed_ms": report.elapsed.as_millis(),
3486                "initial_rss_bytes": report.initial_rss_bytes,
3487                "peak_rss_bytes": report.peak_rss_bytes,
3488                "final_rss_bytes": report.final_rss_bytes,
3489                "resources_released": true,
3490            })
3491        );
3492    }
3493
3494    #[tokio::test]
3495    async fn hundred_thousand_mixed_lifecycles_return_all_internal_resources() {
3496        let report = tokio::time::timeout(
3497            Duration::from_secs(120),
3498            mixed_lifecycle_stress(100_000, Duration::ZERO),
3499        )
3500        .await
3501        .expect("压力测试超时保护触发,需调查进展停滞");
3502        print_stress_report("deterministic-100000", &report);
3503    }
3504
3505    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
3506    #[ignore = "需要显式执行的 30 分钟资源长测"]
3507    async fn thirty_minute_mixed_lifecycles_records_resource_trend() {
3508        let seconds = std::env::var("YDP_SOAK_SECONDS")
3509            .ok()
3510            .and_then(|value| value.parse::<u64>().ok())
3511            .unwrap_or(30 * 60);
3512        let duration = Duration::from_secs(seconds);
3513        let report = tokio::time::timeout(
3514            duration.saturating_add(Duration::from_secs(120)),
3515            mixed_lifecycle_stress(100_000, duration),
3516        )
3517        .await
3518        .expect("资源长测超时保护触发,需调查进展停滞");
3519        print_stress_report("soak", &report);
3520    }
3521}