Skip to main content

open_net/module/net_status/inner/
shared.rs

1//! Engine-scoped network observation ownership. Consumers only retain weak
2//! service contexts and explicit, idempotently releasable demand leases.
3use std::collections::HashSet;
4use std::future::Future;
5use std::pin::Pin;
6use std::sync::{Arc, Mutex, Weak};
7
8use tokio::sync::{mpsc, oneshot, watch};
9
10use super::inner_net_status_client::InnerNetStatusClient;
11use super::network_status_snapshot::NetworkStatusSnapshot;
12use crate::common::CommonEngine;
13use crate::error::{ErrorKind, NetError};
14use crate::net_status::{MonitorState, NetworkSnapshot};
15
16/// A read-only handle to the network facts owned by one `OpenNet` engine.
17/// Cloning or reading it never starts monitoring or extends the engine lifetime.
18/// A context remains tied to its original engine after that engine is dropped.
19#[derive(Clone)]
20pub struct NetworkStatusContext {
21    service: Weak<SharedNetworkService>,
22    facts: watch::Receiver<NetworkSnapshot>,
23    failure: watch::Receiver<Option<NetError>>,
24    gate: watch::Receiver<NetworkStatusSnapshot>,
25}
26impl std::fmt::Debug for NetworkStatusContext {
27    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
28        f.debug_struct("NetworkStatusContext")
29            .finish_non_exhaustive()
30    }
31}
32impl NetworkStatusContext {
33    pub(super) fn name_service(&self) -> Result<Arc<super::names::NameService>, NetError> {
34        self.service
35            .upgrade()
36            .map(|service| service.names.clone())
37            .ok_or_else(|| NetError::from(ErrorKind::Closed))
38    }
39    pub(super) fn observation_source(
40        &self,
41    ) -> Result<super::network_status_snapshot::NetworkStatusSource, NetError> {
42        self.service
43            .upgrade()
44            .map(|service| service.inner.observation_source())
45            .ok_or_else(|| NetError::from(ErrorKind::Closed))
46    }
47    #[cfg(any(windows, test))]
48    pub(super) fn windows_reachability_sampler(
49        &self,
50    ) -> Result<Arc<super::refresh::WindowsSampler>, NetError> {
51        self.service
52            .upgrade()
53            .map(|service| service.inner.windows_reachability_sampler())
54            .ok_or_else(|| NetError::from(ErrorKind::Closed))
55    }
56    /// Read the cached observation without starting or retrying monitoring.
57    pub fn snapshot(&self) -> Result<NetworkSnapshot, NetError> {
58        if let Some(error) = ::tokio::sync::watch::Receiver::borrow(&self.failure).clone() {
59            return Err(error);
60        }
61        match self.service.upgrade() {
62            Some(service) => service.inner.snapshot(),
63            None => Ok(::tokio::sync::watch::Receiver::borrow(&self.facts).clone()),
64        }
65    }
66    pub(crate) fn common_engine(&self) -> Result<Arc<CommonEngine>, NetError> {
67        self.service
68            .upgrade()
69            .map(|service| service.engine.clone())
70            .ok_or_else(|| NetError::from(ErrorKind::Closed))
71    }
72    pub(crate) fn is_closed(&self) -> bool {
73        self.service.upgrade().map_or(true, |service| {
74            match service.admission.lock() {
75                Ok(state) => state.closed,
76                Err(_) => {
77                    crate::log_e!(crate::common::log::log_def::LogType::Engine; "network_service_state", "error", "admission_lock_poisoned");
78                    true
79                }
80            }
81        })
82    }
83    pub(crate) fn acquire(&self) -> Result<NetworkLease, NetError> {
84        let service = self
85            .service
86            .upgrade()
87            .ok_or_else(|| NetError::from(ErrorKind::Closed))?;
88        // A recoverable Failed snapshot remains valid for explicit retry. A
89        // permanent publication error cannot admit new, unusable demand.
90        service.inner.snapshot()?;
91        let id = {
92            let mut state = service.admission.lock().map_err(NetError::from_poison)?;
93            if state.closed {
94                return Err(NetError::from(ErrorKind::Closed));
95            }
96            let id = state
97                .next_id
98                .checked_add(1)
99                .ok_or_else(|| NetError::from(ErrorKind::Internal))?;
100            service
101                .commands
102                .send(Command::Acquire(id))
103                .map_err(|_| NetError::from(ErrorKind::RuntimeUnavailable))?;
104            state.next_id = id;
105            state.active.insert(id);
106            id
107        };
108        Ok(NetworkLease {
109            inner: Arc::new(LeaseState {
110                id,
111                service: Arc::downgrade(&service),
112                released: Mutex::new(None),
113                closed: service.closed.clone(),
114            }),
115        })
116    }
117    pub(crate) fn subscribe_facts(&self) -> watch::Receiver<NetworkSnapshot> {
118        self.facts.clone()
119    }
120    pub(crate) fn subscribe_failure(&self) -> watch::Receiver<Option<NetError>> {
121        self.failure.clone()
122    }
123    pub(crate) fn subscribe_gate(&self) -> watch::Receiver<NetworkStatusSnapshot> {
124        self.gate.clone()
125    }
126}
127
128#[derive(Clone)]
129pub(crate) struct CleanupTicket {
130    finished: watch::Receiver<Option<Result<(), NetError>>>,
131}
132impl CleanupTicket {
133    fn pending() -> (watch::Sender<Option<Result<(), NetError>>>, Self) {
134        let (sender, finished) = watch::channel(None);
135        (sender, Self { finished })
136    }
137    pub(crate) fn is_finished(&self) -> bool {
138        matches!(
139            *::tokio::sync::watch::Receiver::borrow(&self.finished),
140            Some(Ok(()))
141        )
142    }
143    pub(crate) async fn wait(&self) -> Result<(), NetError> {
144        let mut finished = self.finished.clone();
145        loop {
146            if let Some(result) = finished.borrow_and_update().clone() {
147                return result;
148            }
149            finished
150                .changed()
151                .await
152                .map_err(|_| NetError::from(ErrorKind::RuntimeUnavailable))?;
153        }
154    }
155}
156
157#[derive(Clone)]
158pub(crate) struct NetworkLease {
159    inner: Arc<LeaseState>,
160}
161struct LeaseState {
162    id: u64,
163    service: Weak<SharedNetworkService>,
164    released: Mutex<Option<CleanupTicket>>,
165    closed: CleanupTicket,
166}
167impl NetworkLease {
168    pub(crate) fn ensure_started(&self) -> Result<(), NetError> {
169        self.inner.ensure(None)
170    }
171    pub(crate) async fn wait_started(&self) -> Result<NetworkSnapshot, NetError> {
172        let (sender, received) = oneshot::channel();
173        self.inner.ensure(Some(sender))?;
174        received
175            .await
176            .map_err(|_| NetError::from(ErrorKind::RuntimeUnavailable))?
177    }
178    pub(crate) fn release(&self) -> CleanupTicket {
179        self.inner.release()
180    }
181}
182
183impl LeaseState {
184    fn ensure(
185        &self,
186        waiter: Option<oneshot::Sender<Result<NetworkSnapshot, NetError>>>,
187    ) -> Result<(), NetError> {
188        let released = self.released.lock().map_err(NetError::from_poison)?;
189        if released.is_some() {
190            return Err(NetError::from(ErrorKind::Closed));
191        }
192        let service = self
193            .service
194            .upgrade()
195            .ok_or_else(|| NetError::from(ErrorKind::Closed))?;
196        let state = service.admission.lock().map_err(NetError::from_poison)?;
197        if state.closed || !state.active.contains(&self.id) {
198            return Err(NetError::from(ErrorKind::Closed));
199        }
200        service
201            .commands
202            .send(Command::Ensure(self.id, waiter))
203            .map_err(|_| NetError::from(ErrorKind::RuntimeUnavailable))
204    }
205    fn release(&self) -> CleanupTicket {
206        let mut released = match self.released.lock() {
207            Ok(state) => state,
208            Err(poisoned) => {
209                crate::log_e!(crate::common::log::log_def::LogType::Engine; "network_lease_release", "error", "poisoned_lease_recovered");
210                poisoned.into_inner()
211            }
212        };
213        if let Some(ticket) = released.as_ref() {
214            return ticket.clone();
215        }
216        let ticket = match self.service.upgrade() {
217            Some(service) => {
218                let mut admission = match service.admission.lock() {
219                    Ok(state) => state,
220                    Err(poisoned) => {
221                        crate::log_e!(crate::common::log::log_def::LogType::Engine; "network_lease_release", "error", "admission_lock_poisoned_recovered");
222                        poisoned.into_inner()
223                    }
224                };
225                admission.active.remove(&self.id);
226                if admission.closed {
227                    service.closed.clone()
228                } else {
229                    let (sender, ticket) = CleanupTicket::pending();
230                    if let Err(error) = service.commands.send(Command::Release(self.id, sender)) {
231                        if let Command::Release(_, sender) = error.0 {
232                            Completion::new(sender, &service.engine)
233                                .finish(Err(NetError::from(ErrorKind::RuntimeUnavailable)));
234                        }
235                    }
236                    ticket
237                }
238            }
239            None => self.closed.clone(),
240        };
241        *released = Some(ticket.clone());
242        ticket
243    }
244}
245impl Drop for LeaseState {
246    fn drop(&mut self) {
247        self.release();
248    }
249}
250
251struct Admission {
252    closed: bool,
253    next_id: u64,
254    active: HashSet<u64>,
255}
256pub(crate) struct SharedNetworkService {
257    engine: Arc<CommonEngine>,
258    inner: Arc<InnerNetStatusClient>,
259    names: Arc<super::names::NameService>,
260    admission: Mutex<Admission>,
261    commands: mpsc::UnboundedSender<Command>,
262    closed: CleanupTicket,
263}
264enum Command {
265    Acquire(u64),
266    Ensure(
267        u64,
268        Option<oneshot::Sender<Result<NetworkSnapshot, NetError>>>,
269    ),
270    Release(u64, watch::Sender<Option<Result<(), NetError>>>),
271    Close,
272}
273impl SharedNetworkService {
274    pub(crate) fn new(engine: Arc<CommonEngine>) -> Result<Arc<Self>, NetError> {
275        let names = super::names::NameService::new(engine.clone());
276        Self::with_names(engine, names)
277    }
278
279    pub(super) fn with_names(
280        engine: Arc<CommonEngine>,
281        names: Arc<super::names::NameService>,
282    ) -> Result<Arc<Self>, NetError> {
283        let inner = Arc::new(InnerNetStatusClient::new(engine.clone())?);
284        let (commands, receiver) = mpsc::unbounded_channel();
285        let (closed_sender, closed) = CleanupTicket::pending();
286        engine.runtime_handle().spawn(coordinate(
287            inner.clone(),
288            engine.clone(),
289            receiver,
290            closed_sender,
291        ));
292        Ok(Arc::new(Self {
293            engine,
294            inner,
295            names,
296            commands,
297            admission: Mutex::new(Admission {
298                closed: false,
299                next_id: 0,
300                active: HashSet::new(),
301            }),
302            closed,
303        }))
304    }
305    pub(crate) fn context(self: &Arc<Self>) -> NetworkStatusContext {
306        NetworkStatusContext {
307            service: Arc::downgrade(self),
308            facts: self.inner.subscribe_facts(),
309            failure: self.inner.subscribe_failure(),
310            gate: self.inner.subscribe(),
311        }
312    }
313    pub(crate) fn request_close(&self) {
314        let newly_closed = {
315            let mut state = match self.admission.lock() {
316                Ok(state) => state,
317                Err(poisoned) => {
318                    crate::log_e!(crate::common::log::log_def::LogType::Engine; "network_service_close", "error", "admission_lock_poisoned_recovered");
319                    poisoned.into_inner()
320                }
321            };
322            if state.closed {
323                false
324            } else {
325                state.closed = true;
326                state.active.clear();
327                true
328            }
329        };
330        if newly_closed {
331            // Terminal facts become visible before returning. No admission lock
332            // is held while the source wakes its internal SDK readers.
333            self.inner.request_destroy();
334            let _ = self.commands.send(Command::Close);
335            self.names.request_close();
336        }
337    }
338    #[cfg(test)]
339    pub(crate) fn inner_for_test(&self) -> Arc<InnerNetStatusClient> {
340        self.inner.clone()
341    }
342    #[cfg(test)]
343    pub(crate) fn active_consumers_for_test(&self) -> Result<usize, NetError> {
344        Ok(self
345            .admission
346            .lock()
347            .map_err(NetError::from_poison)?
348            .active
349            .len())
350    }
351    pub(crate) async fn shutdown(&self) -> Result<(), NetError> {
352        self.request_close();
353        let monitor = self.closed.wait().await;
354        let names = self.names.wait_cleanup().await;
355        monitor.and(names)
356    }
357}
358
359impl Drop for SharedNetworkService {
360    fn drop(&mut self) {
361        self.request_close();
362    }
363}
364
365type StartFuture = Pin<Box<dyn Future<Output = Result<NetworkSnapshot, NetError>> + Send>>;
366/// This guard also reports task cancellation; dropping a sender is never treated
367/// as proof that provider resources have completed retirement.
368struct Completion {
369    sender: Option<watch::Sender<Option<Result<(), NetError>>>>,
370    engine: Arc<CommonEngine>,
371}
372impl Completion {
373    fn new(
374        sender: watch::Sender<Option<Result<(), NetError>>>,
375        engine: &Arc<CommonEngine>,
376    ) -> Self {
377        Self {
378            sender: Some(sender),
379            engine: engine.clone(),
380        }
381    }
382    fn finish(mut self, result: Result<(), NetError>) {
383        if let Some(sender) = self.sender.take() {
384            let engine = self.engine.clone();
385            self.engine.runtime_handle().spawn_blocking(move || {
386                // A Handle alone cannot keep accepted cleanup work alive.
387                let _runtime_owner = engine;
388                sender.send_replace(Some(result));
389            });
390        }
391    }
392}
393impl Drop for Completion {
394    fn drop(&mut self) {
395        if let Some(sender) = self.sender.take() {
396            let engine = self.engine.clone();
397            self.engine.runtime_handle().spawn_blocking(move || {
398                let _runtime_owner = engine;
399                sender.send_replace(Some(Err(NetError::from(ErrorKind::RuntimeUnavailable))));
400            });
401        }
402    }
403}
404fn notify_waiters(
405    engine: &Arc<CommonEngine>,
406    waiters: Vec<oneshot::Sender<Result<NetworkSnapshot, NetError>>>,
407    result: Result<NetworkSnapshot, NetError>,
408) {
409    for waiter in waiters {
410        let retained_engine = engine.clone();
411        let result = result.clone();
412        engine.runtime_handle().spawn_blocking(move || {
413            let _runtime_owner = retained_engine;
414            // Independent consumers must not share one user-waker stack.
415            let _ = waiter.send(result);
416        });
417    }
418}
419
420fn retire(
421    inner: &InnerNetStatusClient,
422    engine: &Arc<CommonEngine>,
423    permanent: bool,
424    sender: watch::Sender<Option<Result<(), NetError>>>,
425) {
426    let (finished, error) = inner.request_stop(permanent);
427    let completion = Completion::new(sender, engine);
428    engine.runtime_handle().spawn(async move {
429        let result = InnerNetStatusClient::wait_until_finished(finished).await;
430        completion.finish(result.and_then(|()| error.map_or(Ok(()), Err)));
431    });
432}
433async fn coordinate(
434    inner: Arc<InnerNetStatusClient>,
435    engine: Arc<CommonEngine>,
436    mut commands: mpsc::UnboundedReceiver<Command>,
437    closed: watch::Sender<Option<Result<(), NetError>>>,
438) {
439    let closed = Completion::new(closed, &engine);
440    let mut active = HashSet::new();
441    let mut start: Option<StartFuture> = None;
442    let mut waiters = Vec::<oneshot::Sender<Result<NetworkSnapshot, NetError>>>::new();
443    let mut retry_waiters = Vec::new();
444    let mut retry_requested = false;
445    let mut start_revision = 0;
446    loop {
447        tokio::select! {
448            biased;
449            command = commands.recv() => {
450                match command {
451                    Some(Command::Acquire(id)) => { active.insert(id); }
452                    Some(Command::Ensure(id, waiter)) if active.contains(&id) => {
453                        let snapshot = inner.snapshot();
454                        let failed_during_start = start.is_some() && snapshot.as_ref().is_ok_and(|snapshot| {
455                            snapshot.revision > start_revision && matches!(snapshot.state, MonitorState::Failed(_))
456                        });
457                        if failed_during_start {
458                            retry_requested = true;
459                            if let Some(waiter) = waiter { retry_waiters.push(waiter); }
460                        } else {
461                            if let Some(waiter) = waiter { waiters.push(waiter); }
462                            if start.is_none() {
463                                start_revision = snapshot.as_ref().map_or(0, |snapshot| snapshot.revision);
464                                let inner = inner.clone();
465                                start = Some(Box::pin(async move { inner.start().await }));
466                            }
467                        }
468                    }
469                    Some(Command::Ensure(_, waiter)) => {
470                        if let Some(waiter) = waiter { notify_waiters(&engine, vec![waiter], Err(NetError::from(ErrorKind::Closed))); }
471                    }
472                    Some(Command::Release(id, sender)) => {
473                        active.remove(&id);
474                        if active.is_empty() {
475                            drop(start.take());
476                            retry_requested = false;
477                            waiters.append(&mut retry_waiters);
478                            retire(&inner, &engine, false, sender);
479                            let result = inner.snapshot();
480                            notify_waiters(&engine, std::mem::take(&mut waiters), result);
481                        } else {
482                            Completion::new(sender, &engine).finish(Ok(()));
483                        }
484                    }
485                    Some(Command::Close) | None => {
486                        drop(start.take());
487                        waiters.append(&mut retry_waiters);
488                        notify_waiters(&engine, std::mem::take(&mut waiters), Err(NetError::from(ErrorKind::Closed)));
489                        let (finished, error) = inner.request_stop(true);
490                        // No commands need service after the terminal admission
491                        // transition. Only this final shutdown waits for resources.
492                        let result = InnerNetStatusClient::wait_until_finished(finished).await;
493                        closed.finish(result.and_then(|()| error.map_or(Ok(()), Err)));
494                        return;
495                    }
496                }
497            }
498            result = async {
499                match start.as_mut() {
500                    Some(start) => start.await,
501                    None => std::future::pending().await,
502                }
503            } => {
504                start = None;
505                notify_waiters(&engine, std::mem::take(&mut waiters), result);
506                if retry_requested && !active.is_empty() {
507                    retry_requested = false;
508                    waiters = std::mem::take(&mut retry_waiters);
509                    start_revision = inner.snapshot().map_or(0, |snapshot| snapshot.revision);
510                    let inner = inner.clone();
511                    start = Some(Box::pin(async move { inner.start().await }));
512                }
513            }
514        }
515    }
516}
517
518#[cfg(test)]
519mod tests {
520    use super::*;
521    type TestResult = Result<(), Box<dyn std::error::Error + Send + Sync>>;
522    fn check(condition: bool, message: &str) -> TestResult {
523        if condition {
524            Ok(())
525        } else {
526            Err(std::io::Error::other(message).into())
527        }
528    }
529    fn service() -> Result<Arc<SharedNetworkService>, NetError> {
530        SharedNetworkService::new(Arc::new(CommonEngine::new(16, 16)?))
531    }
532    struct BlockingWake {
533        entered: Mutex<Option<oneshot::Sender<()>>>,
534        release: Mutex<std::sync::mpsc::Receiver<()>>,
535    }
536    impl std::task::Wake for BlockingWake {
537        fn wake(self: Arc<Self>) {
538            if let Ok(mut entered) = self.entered.lock() {
539                if let Some(entered) = entered.take() {
540                    let _ = entered.send(());
541                }
542            }
543            if let Ok(release) = self.release.lock() {
544                let _ = release.recv_timeout(std::time::Duration::from_secs(5));
545            }
546        }
547    }
548    #[tokio::test]
549    async fn accepted_waiters_are_not_blocked_by_another_callers_waker() -> TestResult {
550        let engine = Arc::new(CommonEngine::new(16, 16)?);
551        let (entered, entered_wait) = oneshot::channel();
552        let (release, released) = std::sync::mpsc::channel();
553        let waker = std::task::Waker::from(Arc::new(BlockingWake {
554            entered: Mutex::new(Some(entered)),
555            release: Mutex::new(released),
556        }));
557        let (first_sender, mut first) = oneshot::channel();
558        let (second_sender, second) = oneshot::channel();
559        let first_pending = Pin::new(&mut first)
560            .poll(&mut std::task::Context::from_waker(&waker))
561            .is_pending();
562        check(first_pending, "first waiter was already complete")?;
563        notify_waiters(
564            &engine,
565            vec![first_sender, second_sender],
566            Err(NetError::from(ErrorKind::Closed)),
567        );
568        tokio::time::timeout(std::time::Duration::from_secs(5), entered_wait).await??;
569        let second_result = tokio::time::timeout(std::time::Duration::from_secs(2), second).await;
570        let _ = release.send(());
571        check(
572            second_result??.is_err(),
573            "second caller did not receive terminal result",
574        )?;
575        check(
576            first.await?.is_err(),
577            "first caller did not receive terminal result",
578        )?;
579        Ok(())
580    }
581
582    #[tokio::test]
583    async fn accepted_cleanup_notification_keeps_runtime_until_delivery() -> TestResult {
584        let engine = Arc::new(CommonEngine::new(16, 16)?);
585        let (sender, ticket) = CleanupTicket::pending();
586        let completion = Completion::new(sender, &engine);
587        let runtime_owner = Arc::downgrade(&engine);
588        drop(engine);
589        check(
590            runtime_owner.upgrade().is_some(),
591            "accepted cleanup lost its runtime owner",
592        )?;
593        completion.finish(Ok(()));
594        tokio::time::timeout(std::time::Duration::from_secs(5), ticket.wait()).await??;
595        Ok(())
596    }
597
598    #[tokio::test]
599    async fn snapshots_are_inert_and_leases_are_logical_and_idempotent() -> TestResult {
600        let service = service()?;
601        let context = service.context();
602        check(
603            matches!(context.snapshot()?.state, MonitorState::Stopped),
604            "new source is not stopped",
605        )?;
606        let lease = context.acquire()?;
607        let clone = lease.clone();
608        check(
609            service
610                .admission
611                .lock()
612                .map_err(NetError::from_poison)?
613                .active
614                .len()
615                == 1,
616            "clone added demand",
617        )?;
618        lease.release().wait().await?;
619        clone.release().wait().await?;
620        check(
621            service
622                .admission
623                .lock()
624                .map_err(NetError::from_poison)?
625                .active
626                .is_empty(),
627            "released demand leaked",
628        )?;
629        check(
630            matches!(context.snapshot()?.state, MonitorState::Stopped),
631            "acquisition started monitoring",
632        )?;
633        service.shutdown().await?;
634        Ok(())
635    }
636    #[tokio::test]
637    async fn closed_context_rejects_new_leases_and_preserves_terminal_cache() -> TestResult {
638        let service = service()?;
639        let context = service.context();
640        service.request_close();
641        check(context.acquire().is_err(), "closed context admitted demand")?;
642        check(
643            matches!(context.snapshot()?.state, MonitorState::Closed),
644            "close was not synchronous",
645        )?;
646        service.shutdown().await?;
647        drop(service);
648        check(
649            matches!(context.snapshot()?.state, MonitorState::Closed),
650            "terminal cache was lost",
651        )?;
652        Ok(())
653    }
654    fn gated_service() -> Result<
655        (
656            Arc<SharedNetworkService>,
657            mpsc::UnboundedReceiver<oneshot::Sender<()>>,
658            Arc<std::sync::atomic::AtomicUsize>,
659        ),
660        NetError,
661    > {
662        let service = service()?;
663        let (attempts, receiver) = mpsc::unbounded_channel();
664        let calls = Arc::new(std::sync::atomic::AtomicUsize::new(0));
665        let factory_calls = calls.clone();
666        service
667            .inner
668            .set_monitor_factory_for_test(Arc::new(move || {
669                factory_calls.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
670                let (release, ready) = oneshot::channel();
671                let _ = attempts.send(release);
672                Box::pin(async move {
673                    let _ = ready.await;
674                    Err(NetError::from(ErrorKind::Io))
675                })
676            }))?;
677        Ok((service, receiver, calls))
678    }
679    async fn attempt(
680        receiver: &mut mpsc::UnboundedReceiver<oneshot::Sender<()>>,
681    ) -> Result<oneshot::Sender<()>, Box<dyn std::error::Error + Send + Sync>> {
682        Ok(
683            tokio::time::timeout(std::time::Duration::from_secs(5), receiver.recv())
684                .await?
685                .ok_or("factory missing")?,
686        )
687    }
688    #[tokio::test]
689    async fn concurrent_demand_shares_pending_initialization_and_nonlast_release_is_isolated(
690    ) -> TestResult {
691        let (service, mut attempts, calls) = gated_service()?;
692        let a = service.context().acquire()?;
693        let b = service.context().acquire()?;
694        a.ensure_started()?;
695        b.ensure_started()?;
696        let release = attempt(&mut attempts).await?;
697        a.release().wait().await?;
698        check(
699            calls.load(std::sync::atomic::Ordering::SeqCst) == 1,
700            "concurrent demand duplicated provider",
701        )?;
702        check(
703            !release.is_closed(),
704            "nonlast release cancelled shared startup",
705        )?;
706        let mut waiting = Box::pin(b.wait_started());
707        check(
708            futures::poll!(&mut waiting).is_pending(),
709            "start waiter unexpectedly completed",
710        )?;
711        // Polling wait_started only queues Ensure. A subsequent nonlast release
712        // is a FIFO acknowledgement that the coordinator admitted this waiter
713        // before we fail initialization. Otherwise it could legitimately see a
714        // later Ensure as a retry, leaving that new generation gated forever.
715        let barrier = service.context().acquire()?;
716        barrier.release().wait().await?;
717        let _ = release.send(());
718        let result = tokio::time::timeout(std::time::Duration::from_secs(5), waiting).await?;
719        check(
720            matches!(result, Err(error) if error.kind() == ErrorKind::Io),
721            "shared startup error lost",
722        )?;
723        service.shutdown().await?;
724        Ok(())
725    }
726    #[tokio::test]
727    async fn failed_generation_can_retry_with_existing_lease_and_live_fact_stream() -> TestResult {
728        let (service, mut attempts, calls) = gated_service()?;
729        let context = service.context();
730        let lease = context.acquire()?;
731        let mut facts = context.subscribe_facts();
732        let first = lease.clone();
733        let waiting = tokio::spawn(async move { first.wait_started().await });
734        let _ = attempt(&mut attempts).await?.send(());
735        check(waiting.await?.is_err(), "failure was hidden")?;
736        check(
737            matches!(context.snapshot()?.state, MonitorState::Failed(_)),
738            "failure snapshot absent",
739        )?;
740        lease.ensure_started()?;
741        let second = attempt(&mut attempts).await?;
742        check(
743            calls.load(std::sync::atomic::Ordering::SeqCst) == 2,
744            "existing demand could not retry",
745        )?;
746        check(
747            facts.changed().await.is_ok(),
748            "recoverable failure closed stream",
749        )?;
750        lease.release().wait().await?;
751        check(second.is_closed(), "last release did not cancel retry")?;
752        service.shutdown().await?;
753        Ok(())
754    }
755    #[tokio::test]
756    async fn close_during_pending_start_finishes_waiters_and_prevents_revival() -> TestResult {
757        let (service, mut attempts, _) = gated_service()?;
758        let context = service.context();
759        let lease = context.acquire()?;
760        let waiter = lease.clone();
761        let waiting = tokio::spawn(async move { waiter.wait_started().await });
762        let _attempt = attempt(&mut attempts).await?;
763        service.request_close();
764        check(
765            matches!(context.snapshot()?.state, MonitorState::Closed),
766            "close did not publish terminal",
767        )?;
768        check(
769            matches!(waiting.await?, Err(error) if error.kind() == ErrorKind::Closed),
770            "pending start survived close",
771        )?;
772        lease.release().wait().await?;
773        check(context.acquire().is_err(), "closed service revived")?;
774        service.shutdown().await?;
775        Ok(())
776    }
777    #[tokio::test]
778    async fn service_drop_does_not_require_external_context_or_lease_drop() -> TestResult {
779        let (service, mut attempts, _) = gated_service()?;
780        let context = service.context();
781        let lease = context.acquire()?;
782        lease.ensure_started()?;
783        let _attempt = attempt(&mut attempts).await?;
784        drop(service);
785        check(
786            matches!(context.snapshot()?.state, MonitorState::Closed),
787            "external context kept engine alive",
788        )?;
789        lease.release().wait().await?;
790        check(
791            lease.ensure_started().is_err(),
792            "released context restarted engine",
793        )?;
794        Ok(())
795    }
796}
797
798#[cfg(test)]
799#[path = "shared_regression_tests.rs"]
800mod regression_tests;