Skip to main content

hyprstream_rpc/
resolver.rs

1//! Service endpoint resolution abstraction.
2//!
3//! Defines the `Resolver` trait for converting service names to transport
4//! endpoints. The trait is async to support federation (network-based
5//! resolution) in addition to local registry lookups.
6//!
7//! # Architecture
8//!
9//! ```text
10//! hyprstream-rpc:     trait Resolver + SocketKind + pluggable global
11//! hyprstream-discovery: EndpointRegistry implements Resolver (local)
12//! future:              DiscoveryClient implements Resolver (remote/federated)
13//! ```
14//!
15//! # Usage
16//!
17//! ```ignore
18//! use hyprstream_rpc::{Resolver, SocketKind};
19//!
20//! async fn connect(resolver: &dyn Resolver) -> Result<()> {
21//!     let endpoint = resolver.resolve("inference", SocketKind::Rep).await?;
22//!     // Use endpoint...
23//!     Ok(())
24//! }
25//! ```
26
27use std::collections::BTreeSet;
28use std::sync::Arc;
29
30use anyhow::anyhow;
31use parking_lot::RwLock;
32
33#[cfg(test)]
34use crate::identity::Did;
35use crate::registry::SocketKind;
36#[cfg(test)]
37use crate::rpc_client::{CallOptions, RpcClient};
38#[cfg(test)]
39use crate::stream_consumer::StreamHandle;
40use crate::transport::{EndpointType, TransportConfig};
41#[cfg(test)]
42use crate::VerifyingKey;
43
44/// Canonical service-resolution request.
45#[derive(Debug, Clone, PartialEq, Eq)]
46pub struct ServiceQuery {
47    pub service_name: String,
48    pub required_capabilities: BTreeSet<String>,
49    pub profile: ResolverProfile,
50    pub max_attempts: usize,
51}
52
53impl ServiceQuery {
54    pub fn network(service_name: impl Into<String>) -> anyhow::Result<Self> {
55        Self::new(
56            service_name,
57            ["hyprstream-rpc/1".to_owned()],
58            ResolverProfile::NativeIrohRequired,
59            3,
60        )
61    }
62
63    /// Native MoQ-only capability query (the Event barrier has no RPC surface).
64    pub fn network_moq(service_name: impl Into<String>) -> anyhow::Result<Self> {
65        Self::new(
66            service_name,
67            ["hyprstream-moq/1".to_owned()],
68            ResolverProfile::NativeIrohRequired,
69            3,
70        )
71    }
72
73    /// Construct the explicit browser/public-edge query. Browser clients use
74    /// WebTransport over QUIC; Iroh is deliberately not a browser carrier.
75    pub fn browser(service_name: impl Into<String>) -> anyhow::Result<Self> {
76        Self::new(
77            service_name,
78            ["hyprstream-rpc/1".to_owned()],
79            ResolverProfile::BrowserWebTransport,
80            1,
81        )
82    }
83
84    pub fn new(
85        service_name: impl Into<String>,
86        capabilities: impl IntoIterator<Item = String>,
87        profile: ResolverProfile,
88        max_attempts: usize,
89    ) -> anyhow::Result<Self> {
90        let service_name = canonical_service_name(&service_name.into())?;
91        anyhow::ensure!(max_attempts > 0, "resolution max_attempts must be non-zero");
92        Ok(Self {
93            service_name,
94            required_capabilities: capabilities.into_iter().collect(),
95            profile,
96            max_attempts: max_attempts.min(16),
97        })
98    }
99}
100
101/// Current accepted-state projection consumed by service resolution.
102///
103/// It contains only owned public material. Its producer is responsible for
104/// obtaining it through the PDS checkpoint-verifying typed read.
105#[derive(Debug, Clone, PartialEq, Eq)]
106#[cfg(test)]
107pub struct AcceptedStateEvidence {
108    pub service_did: Did,
109    pub digest: [u8; 64],
110    pub epoch: u64,
111    pub expires_at_unix_ms: i64,
112    pub response_ed25519: [u8; 32],
113    pub response_ml_dsa65: Vec<u8>,
114}
115
116/// An anchored, suite-complete request recipient and its current key id.
117#[derive(Debug, Clone, PartialEq, Eq)]
118#[cfg(test)]
119pub struct AnchoredKemRecipient {
120    pub key_id: String,
121    pub recipient: crate::crypto::hybrid_kem::RecipientPublic,
122    pub not_after_unix_ms: i64,
123}
124
125/// One owned candidate acquired from Discovery/PDS.
126#[derive(Debug, Clone, PartialEq, Eq)]
127#[cfg(test)]
128pub struct ServiceCandidate {
129    pub service_name: String,
130    pub service_did: Did,
131    pub response_verifying_key: [u8; 32],
132    pub response_ml_dsa65: Vec<u8>,
133    pub response_key_id: String,
134    pub request_kem_recipient: Option<AnchoredKemRecipient>,
135    pub transport: TransportConfig,
136    pub capabilities: BTreeSet<String>,
137    pub accepted_state: AcceptedStateEvidence,
138    pub source_signer: [u8; 32],
139    pub expires_at_unix_ms: i64,
140}
141
142/// Non-secret deterministic audit record for filter/rank/select.
143#[derive(Debug, Clone, PartialEq, Eq)]
144#[cfg(test)]
145pub struct CandidateDecision {
146    pub candidate_fingerprint: String,
147    pub accepted: bool,
148    pub reason: String,
149}
150
151/// Evidence carried with the selected atomic result.
152#[derive(Debug, Clone, PartialEq, Eq)]
153#[cfg(test)]
154pub struct ResolutionEvidence {
155    pub accepted_state_digest: [u8; 64],
156    pub accepted_state_epoch: u64,
157    pub selected_fingerprint: String,
158    pub ordered_decisions: Vec<CandidateDecision>,
159}
160
161/// One identity-bound, owned service resolution result.
162#[derive(Debug, Clone)]
163#[cfg(test)]
164pub struct SelectedService {
165    service_name: String,
166    service_did: Did,
167    response_verifying_key: VerifyingKey,
168    response_ml_dsa65: Vec<u8>,
169    response_key_id: String,
170    request_kem_recipient: AnchoredKemRecipient,
171    transport: TransportConfig,
172    capabilities: BTreeSet<String>,
173    expires_at_unix_ms: i64,
174    evidence: ResolutionEvidence,
175}
176
177#[cfg(test)]
178impl SelectedService {
179    pub fn same_authority(&self, other: &Self) -> bool {
180        self.service_name == other.service_name
181            && self.service_did == other.service_did
182            && self.response_verifying_key == other.response_verifying_key
183            && self.response_ml_dsa65 == other.response_ml_dsa65
184            && self.response_key_id == other.response_key_id
185            && self.request_kem_recipient == other.request_kem_recipient
186            && self.evidence.accepted_state_digest == other.evidence.accepted_state_digest
187            && self.evidence.accepted_state_epoch == other.evidence.accepted_state_epoch
188    }
189    pub fn service_name(&self) -> &str {
190        &self.service_name
191    }
192
193    pub fn service_did(&self) -> &Did {
194        &self.service_did
195    }
196
197    pub fn response_verifying_key(&self) -> VerifyingKey {
198        self.response_verifying_key
199    }
200
201    pub fn response_ml_dsa65(&self) -> &[u8] {
202        &self.response_ml_dsa65
203    }
204
205    pub fn response_key_id(&self) -> &str {
206        &self.response_key_id
207    }
208
209    pub fn request_kem_recipient(&self) -> &AnchoredKemRecipient {
210        &self.request_kem_recipient
211    }
212
213    pub fn transport(&self) -> &TransportConfig {
214        &self.transport
215    }
216
217    pub fn capabilities(&self) -> &BTreeSet<String> {
218        &self.capabilities
219    }
220
221    pub fn evidence(&self) -> &ResolutionEvidence {
222        &self.evidence
223    }
224
225    /// Re-check the snapshot clock boundary immediately before dialing/sealing.
226    pub fn ensure_fresh(&self, now_unix_ms: i64) -> anyhow::Result<()> {
227        anyhow::ensure!(
228            now_unix_ms < self.expires_at_unix_ms,
229            "resolved service snapshot expired; re-resolution required"
230        );
231        anyhow::ensure!(
232            now_unix_ms < self.request_kem_recipient.not_after_unix_ms,
233            "resolved request KEM recipient expired; re-resolution required"
234        );
235        Ok(())
236    }
237
238    /// Build the exact per-resolution crypto stores used by the dial path.
239    /// No global trust-store lookup occurs here.
240    pub fn crypto_stores(
241        &self,
242    ) -> anyhow::Result<(
243        Arc<dyn crate::crypto::hybrid_kem::KemTrustStore>,
244        Arc<dyn crate::envelope::PqTrustStore>,
245    )> {
246        let ed = self.response_verifying_key.to_bytes();
247        let mut kem = crate::crypto::hybrid_kem::KeyedKemTrustStore::new();
248        kem.bind(ed, self.request_kem_recipient.recipient.clone());
249        let pq_key = crate::crypto::pq::ml_dsa_vk_from_bytes(&self.response_ml_dsa65)
250            .map_err(|e| anyhow!("invalid resolved ML-DSA-65 response key: {e}"))?;
251        let mut pq = crate::envelope::KeyedPqTrustStore::new();
252        pq.bind(ed, &pq_key);
253        Ok((Arc::new(kem), Arc::new(pq)))
254    }
255}
256
257/// Identity-bound service resolver used by generated clients.
258#[async_trait::async_trait]
259#[cfg(test)]
260pub trait ServiceResolver: Send + Sync {
261    async fn resolve_service(&self, query: ServiceQuery) -> anyhow::Result<SelectedService>;
262
263    /// Resolve the complete deterministic same-authority retry set.  The
264    /// default preserves compatibility for resolvers with a single reach.
265    async fn resolve_service_candidates(
266        &self,
267        query: ServiceQuery,
268    ) -> anyhow::Result<Vec<SelectedService>> {
269        Ok(vec![self.resolve_service(query).await?])
270    }
271
272    /// Consult the authoritative accepted-state source immediately before dial.
273    /// Implementations reject an advanced, expired, or missing head.
274    async fn ensure_current(&self, resolved: &SelectedService) -> anyhow::Result<()>;
275}
276
277/// RPC client which retains the identity-bound resolver through every lazy
278/// network operation.  It resolves and checks the accepted head immediately
279/// before sealing, and constructs the transport and crypto stores from the
280/// same snapshot.  A transport failure may advance only through the bounded,
281/// deterministic same-authority alternatives returned by that resolver.
282#[cfg(test)]
283pub struct ResolvedRpcClient {
284    service_name: String,
285    signing_key: crate::crypto::SigningKey,
286    token: Option<String>,
287    resolver: Arc<dyn ServiceResolver>,
288    request_id: std::sync::atomic::AtomicU64,
289}
290
291#[cfg(test)]
292impl ResolvedRpcClient {
293    pub fn new(
294        service_name: impl Into<String>,
295        signing_key: crate::crypto::SigningKey,
296        token: Option<String>,
297        resolver: Arc<dyn ServiceResolver>,
298    ) -> anyhow::Result<Self> {
299        let service_name = canonical_service_name(&service_name.into())?;
300        Ok(Self {
301            service_name,
302            signing_key,
303            token,
304            resolver,
305            request_id: std::sync::atomic::AtomicU64::new(1),
306        })
307    }
308
309    async fn snapshots(&self) -> anyhow::Result<Vec<SelectedService>> {
310        let query = ServiceQuery::network(self.service_name.clone())?;
311        let max_attempts = query.max_attempts;
312        let resolved = self.resolver.resolve_service_candidates(query).await?;
313        anyhow::ensure!(
314            !resolved.is_empty(),
315            "resolver returned no validated alternatives"
316        );
317        let authority = &resolved[0];
318        anyhow::ensure!(
319            resolved.iter().all(|item| item.same_authority(authority)),
320            "resolver retry set crosses service authority"
321        );
322        Ok(resolved.into_iter().take(max_attempts).collect())
323    }
324
325    fn client_for(&self, snapshot: &SelectedService) -> anyhow::Result<Arc<dyn RpcClient>> {
326        let (kem, pq) = snapshot.crypto_stores()?;
327        let signer = crate::signer::LocalSigner::new(self.signing_key.clone());
328        crate::dial::dial_with_crypto_stores(
329            snapshot.transport(),
330            signer,
331            Some(snapshot.response_verifying_key()),
332            self.token.clone(),
333            Some(kem),
334            Some(pq),
335        )
336    }
337
338    async fn attempt<T, F, Fut>(&self, mut call: F) -> anyhow::Result<T>
339    where
340        F: FnMut(Arc<dyn RpcClient>) -> Fut,
341        Fut: std::future::Future<Output = anyhow::Result<T>>,
342    {
343        for refresh in 0..2 {
344            let mut last_transport_error = None;
345            let mut invalidated = None;
346            for snapshot in self.snapshots().await? {
347                if let Err(error) = self.resolver.ensure_current(&snapshot).await {
348                    invalidated = Some(error);
349                    break;
350                }
351                let client = self.client_for(&snapshot)?;
352                match call(client).await {
353                    Ok(value) => return Ok(value),
354                    Err(error)
355                        if crate::transport_traits::is_pre_dispatch_transport_error(&error) =>
356                    {
357                        last_transport_error = Some(error);
358                    }
359                    Err(error) => return Err(error),
360                }
361            }
362            if let Some(error) = invalidated {
363                if refresh == 0 {
364                    continue;
365                }
366                return Err(anyhow!(
367                    "resolved service remained invalid after re-resolution: {error}"
368                ));
369            }
370            return Err(last_transport_error
371                .unwrap_or_else(|| anyhow!("validated same-authority alternatives exhausted")));
372        }
373        unreachable!("bounded re-resolution loop always returns")
374    }
375}
376
377#[async_trait::async_trait]
378#[cfg(test)]
379impl RpcClient for ResolvedRpcClient {
380    async fn call(&self, payload: Vec<u8>) -> anyhow::Result<Vec<u8>> {
381        self.attempt(|c| {
382            let p = payload.clone();
383            async move { c.call(p).await }
384        })
385        .await
386    }
387    async fn call_for_service(&self, service: &str, payload: Vec<u8>) -> anyhow::Result<Vec<u8>> {
388        anyhow::ensure!(
389            service == self.service_name,
390            "generated service authority mismatch"
391        );
392        let service = service.to_owned();
393        self.attempt(|c| {
394            let p = payload.clone();
395            let s = service.clone();
396            async move { c.call_for_service(&s, p).await }
397        })
398        .await
399    }
400    async fn call_for_service_with_method(
401        &self,
402        service: &str,
403        method_discriminator: u16,
404        payload: Vec<u8>,
405    ) -> anyhow::Result<Vec<u8>> {
406        anyhow::ensure!(
407            service == self.service_name,
408            "generated service authority mismatch"
409        );
410        let service = service.to_owned();
411        self.attempt(|c| {
412            let p = payload.clone();
413            let s = service.clone();
414            async move {
415                c.call_for_service_with_method(&s, method_discriminator, p)
416                    .await
417            }
418        })
419        .await
420    }
421    async fn call_with_options(
422        &self,
423        payload: Vec<u8>,
424        options: CallOptions,
425    ) -> anyhow::Result<Vec<u8>> {
426        self.attempt(|c| {
427            let p = payload.clone();
428            let o = options.clone();
429            async move { c.call_with_options(p, o).await }
430        })
431        .await
432    }
433    async fn call_with_options_for_service(
434        &self,
435        service: &str,
436        payload: Vec<u8>,
437        options: CallOptions,
438    ) -> anyhow::Result<Vec<u8>> {
439        anyhow::ensure!(
440            service == self.service_name,
441            "generated service authority mismatch"
442        );
443        let service = service.to_owned();
444        self.attempt(|c| {
445            let p = payload.clone();
446            let o = options.clone();
447            let s = service.clone();
448            async move { c.call_with_options_for_service(&s, p, o).await }
449        })
450        .await
451    }
452
453    async fn call_with_options_for_service_with_method(
454        &self,
455        service: &str,
456        method_discriminator: u16,
457        payload: Vec<u8>,
458        options: CallOptions,
459    ) -> anyhow::Result<Vec<u8>> {
460        anyhow::ensure!(
461            service == self.service_name,
462            "generated service authority mismatch"
463        );
464        let service = service.to_owned();
465        self.attempt(|client| {
466            let payload = payload.clone();
467            let options = options.clone();
468            let service = service.clone();
469            async move {
470                client
471                    .call_with_options_for_service_with_method(
472                        &service,
473                        method_discriminator,
474                        payload,
475                        options,
476                    )
477                    .await
478            }
479        })
480        .await
481    }
482
483    async fn call_streaming(
484        &self,
485        payload: Vec<u8>,
486        ephemeral: [u8; 32],
487    ) -> anyhow::Result<Vec<u8>> {
488        self.attempt(|c| {
489            let p = payload.clone();
490            async move { c.call_streaming(p, ephemeral).await }
491        })
492        .await
493    }
494    async fn call_streaming_for_service(
495        &self,
496        service: &str,
497        payload: Vec<u8>,
498        ephemeral: [u8; 32],
499    ) -> anyhow::Result<Vec<u8>> {
500        anyhow::ensure!(
501            service == self.service_name,
502            "generated service authority mismatch"
503        );
504        let service = service.to_owned();
505        self.attempt(|c| {
506            let p = payload.clone();
507            let s = service.clone();
508            async move { c.call_streaming_for_service(&s, p, ephemeral).await }
509        })
510        .await
511    }
512    async fn call_streaming_for_service_with_method(
513        &self,
514        service: &str,
515        method_discriminator: u16,
516        payload: Vec<u8>,
517        ephemeral: [u8; 32],
518    ) -> anyhow::Result<Vec<u8>> {
519        anyhow::ensure!(
520            service == self.service_name,
521            "generated service authority mismatch"
522        );
523        let service = service.to_owned();
524        self.attempt(|c| {
525            let p = payload.clone();
526            let s = service.clone();
527            async move {
528                c.call_streaming_for_service_with_method(&s, method_discriminator, p, ephemeral)
529                    .await
530            }
531        })
532        .await
533    }
534    async fn open_stream(&self, payload: Vec<u8>) -> anyhow::Result<Box<dyn StreamHandle>> {
535        self.attempt(|c| {
536            let p = payload.clone();
537            async move { c.open_stream(p).await }
538        })
539        .await
540    }
541    async fn open_stream_from_info(
542        &self,
543        info: crate::stream_info::StreamInfo,
544        secret: [u8; 32],
545        public: [u8; 32],
546    ) -> anyhow::Result<Box<dyn StreamHandle>> {
547        self.attempt(|c| {
548            let i = info.clone();
549            async move { c.open_stream_from_info(i, secret, public).await }
550        })
551        .await
552    }
553    fn next_id(&self) -> u64 {
554        self.request_id
555            .fetch_add(1, std::sync::atomic::Ordering::Relaxed)
556    }
557}
558
559fn canonical_service_name(name: &str) -> anyhow::Result<String> {
560    let canonical = name.trim().to_ascii_lowercase();
561    anyhow::ensure!(!canonical.is_empty(), "service name is empty");
562    anyhow::ensure!(
563        canonical
564            .bytes()
565            .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'-'),
566        "service name contains non-canonical characters"
567    );
568    anyhow::ensure!(canonical == name, "service name is not canonical");
569    Ok(canonical)
570}
571
572#[cfg(test)]
573fn network_reach(transport: &TransportConfig) -> bool {
574    matches!(
575        transport.endpoint,
576        EndpointType::Quic { .. } | EndpointType::Iroh { .. }
577    )
578}
579
580#[cfg(test)]
581fn native_iroh_reach(transport: &TransportConfig) -> bool {
582    matches!(transport.endpoint, EndpointType::Iroh { .. })
583}
584
585#[cfg(test)]
586fn browser_webtransport_reach(transport: &TransportConfig) -> bool {
587    matches!(transport.endpoint, EndpointType::Quic { .. })
588}
589
590#[cfg(test)]
591fn transport_fingerprint(transport: &TransportConfig) -> String {
592    let bytes = format!("{transport:?}");
593    blake3::hash(bytes.as_bytes()).to_hex().to_string()
594}
595
596#[cfg(test)]
597fn hash_framed(hasher: &mut blake3::Hasher, bytes: &[u8]) {
598    hasher.update(&(bytes.len() as u64).to_be_bytes());
599    hasher.update(bytes);
600}
601
602#[cfg(test)]
603fn candidate_fingerprint(candidate: &ServiceCandidate) -> String {
604    let mut h = blake3::Hasher::new();
605    hash_framed(&mut h, candidate.service_name.as_bytes());
606    hash_framed(&mut h, candidate.service_did.as_str().as_bytes());
607    h.update(&candidate.response_verifying_key);
608    hash_framed(&mut h, &candidate.response_ml_dsa65);
609    hash_framed(&mut h, candidate.response_key_id.as_bytes());
610    if let Some(kem) = &candidate.request_kem_recipient {
611        hash_framed(&mut h, kem.key_id.as_bytes());
612        hash_framed(&mut h, &kem.recipient.encode());
613    }
614    hash_framed(
615        &mut h,
616        transport_fingerprint(&candidate.transport).as_bytes(),
617    );
618    for capability in &candidate.capabilities {
619        hash_framed(&mut h, capability.as_bytes());
620    }
621    h.update(&candidate.accepted_state.digest);
622    h.update(&candidate.accepted_state.epoch.to_be_bytes());
623    hash_framed(
624        &mut h,
625        candidate.accepted_state.service_did.as_str().as_bytes(),
626    );
627    h.update(&candidate.accepted_state.expires_at_unix_ms.to_be_bytes());
628    h.update(&candidate.accepted_state.response_ed25519);
629    hash_framed(&mut h, &candidate.accepted_state.response_ml_dsa65);
630    h.update(&candidate.source_signer);
631    h.update(&candidate.expires_at_unix_ms.to_be_bytes());
632    if let Some(kem) = &candidate.request_kem_recipient {
633        h.update(&kem.not_after_unix_ms.to_be_bytes());
634    }
635    h.finalize().to_hex().to_string()
636}
637
638#[cfg(test)]
639fn rejection_reason(
640    query: &ServiceQuery,
641    candidate: &ServiceCandidate,
642    now_unix_ms: i64,
643) -> Option<&'static str> {
644    if canonical_service_name(&candidate.service_name)
645        .ok()
646        .as_deref()
647        != Some(query.service_name.as_str())
648    {
649        return Some("service-name-mismatch");
650    }
651    if !candidate.service_did.is_did_at9p()
652        || candidate.service_did != candidate.accepted_state.service_did
653    {
654        return Some("missing-or-mismatched-accepted-identity");
655    }
656    if candidate.source_signer != candidate.accepted_state.response_ed25519 {
657        return Some("announcement-signer-not-current");
658    }
659    if candidate.response_verifying_key != candidate.accepted_state.response_ed25519
660        || candidate.response_ml_dsa65 != candidate.accepted_state.response_ml_dsa65
661    {
662        return Some("response-key-not-current");
663    }
664    if !candidate
665        .response_key_id
666        .starts_with(&format!("{}#", candidate.service_did))
667        || crate::crypto::pq::ml_dsa_vk_from_bytes(&candidate.response_ml_dsa65).is_err()
668    {
669        return Some("missing-or-invalid-response-key-material");
670    }
671    if !query
672        .required_capabilities
673        .is_subset(&candidate.capabilities)
674    {
675        return Some("missing-capability");
676    }
677    if candidate.expires_at_unix_ms <= now_unix_ms
678        || candidate.accepted_state.expires_at_unix_ms <= now_unix_ms
679    {
680        return Some("expired-candidate-or-state");
681    }
682    match query.profile {
683        ResolverProfile::NetworkDiscovery if !network_reach(&candidate.transport) => {
684            return Some("local-reach-for-network-profile");
685        }
686        ResolverProfile::NativeIrohRequired if !native_iroh_reach(&candidate.transport) => {
687            return Some("non-iroh-reach-for-native-profile");
688        }
689        ResolverProfile::BrowserWebTransport
690            if !browser_webtransport_reach(&candidate.transport) =>
691        {
692            return Some("non-quic-reach-for-browser-profile");
693        }
694        ResolverProfile::LocalInproc
695            if !matches!(candidate.transport.endpoint, EndpointType::Inproc { .. }) =>
696        {
697            return Some("non-inproc-reach-for-local-profile");
698        }
699        ResolverProfile::Ipc
700            if !matches!(
701                candidate.transport.endpoint,
702                EndpointType::Ipc { .. } | EndpointType::SystemdFd { .. }
703            ) =>
704        {
705            return Some("non-ipc-reach-for-ipc-profile");
706        }
707        _ => {}
708    }
709    let Some(kem) = &candidate.request_kem_recipient else {
710        return Some("missing-request-kem-recipient");
711    };
712    if !kem
713        .key_id
714        .starts_with(&format!("{}#", candidate.service_did))
715        || kem.not_after_unix_ms <= now_unix_ms
716        || kem.recipient.suite_id != crate::crypto::hybrid_kem::SuiteId::HyKemX25519MlKem768
717        || kem.recipient.eks.len() != kem.recipient.suite_id.components().len()
718        || crate::crypto::hybrid_kem::RecipientPublic::decode(&kem.recipient.encode()).is_err()
719    {
720        return Some("invalid-expired-or-nonhybrid-kem-recipient");
721    }
722    None
723}
724
725/// Run a bounded retry over an already validated deterministic order.
726/// The callback cannot request or substitute any out-of-plan candidate.
727#[cfg(test)]
728pub async fn retry_validated_candidates<T, F, Fut>(
729    mut ordered: Vec<SelectedService>,
730    max_attempts: usize,
731    mut attempt: F,
732) -> anyhow::Result<T>
733where
734    F: FnMut(&SelectedService) -> Fut,
735    Fut: std::future::Future<Output = anyhow::Result<T>>,
736{
737    anyhow::ensure!(max_attempts > 0, "retry bound must be non-zero");
738    let authority = ordered
739        .first()
740        .ok_or_else(|| anyhow!("validated retry set is empty"))?;
741    anyhow::ensure!(
742        ordered.iter().all(|resolved| {
743            resolved.service_name == authority.service_name
744                && resolved.service_did == authority.service_did
745                && resolved.response_verifying_key == authority.response_verifying_key
746                && resolved.response_ml_dsa65 == authority.response_ml_dsa65
747                && resolved.response_key_id == authority.response_key_id
748                && resolved.request_kem_recipient == authority.request_kem_recipient
749                && resolved.evidence.accepted_state_digest
750                    == authority.evidence.accepted_state_digest
751                && resolved.evidence.accepted_state_epoch == authority.evidence.accepted_state_epoch
752        }),
753        "validated retry set crosses service authority"
754    );
755    ordered.sort_by(|a, b| {
756        b.expires_at_unix_ms
757            .cmp(&a.expires_at_unix_ms)
758            .then_with(|| {
759                transport_fingerprint(&a.transport).cmp(&transport_fingerprint(&b.transport))
760            })
761            .then_with(|| {
762                a.evidence
763                    .selected_fingerprint
764                    .cmp(&b.evidence.selected_fingerprint)
765            })
766    });
767    ordered.dedup_by(|a, b| a.evidence.selected_fingerprint == b.evidence.selected_fingerprint);
768    let mut last_error = None;
769    for resolved in ordered.iter().take(max_attempts.min(16)) {
770        match attempt(resolved).await {
771            Ok(value) => return Ok(value),
772            Err(error) => last_error = Some(error),
773        }
774    }
775    Err(last_error.unwrap_or_else(|| anyhow!("validated retry set exhausted")))
776}
777
778/// Filter, canonicalize, rank, and select without insertion-order dependence.
779#[cfg(test)]
780pub fn select_service_candidate(
781    query: &ServiceQuery,
782    candidates: Vec<ServiceCandidate>,
783    now_unix_ms: i64,
784) -> anyhow::Result<SelectedService> {
785    let mut decisions = Vec::with_capacity(candidates.len());
786    let mut valid = Vec::new();
787    for candidate in candidates {
788        let fingerprint = candidate_fingerprint(&candidate);
789        if let Some(reason) = rejection_reason(query, &candidate, now_unix_ms) {
790            decisions.push(CandidateDecision {
791                candidate_fingerprint: fingerprint,
792                accepted: false,
793                reason: reason.to_owned(),
794            });
795        } else {
796            decisions.push(CandidateDecision {
797                candidate_fingerprint: fingerprint.clone(),
798                accepted: true,
799                reason: "validated".to_owned(),
800            });
801            valid.push((fingerprint, candidate));
802        }
803    }
804    anyhow::ensure!(!valid.is_empty(), "no validated service candidates");
805
806    let authority = &valid[0].1;
807    anyhow::ensure!(
808        valid.iter().all(|(_, candidate)| {
809            candidate.service_did == authority.service_did
810                && candidate.response_verifying_key == authority.response_verifying_key
811                && candidate.response_ml_dsa65 == authority.response_ml_dsa65
812                && candidate.response_key_id == authority.response_key_id
813                && candidate.request_kem_recipient == authority.request_kem_recipient
814                && candidate.accepted_state == authority.accepted_state
815        }),
816        "ambiguous validated service authority"
817    );
818
819    valid.sort_by(|(af, a), (bf, b)| {
820        b.accepted_state
821            .epoch
822            .cmp(&a.accepted_state.epoch)
823            .then_with(|| b.expires_at_unix_ms.cmp(&a.expires_at_unix_ms))
824            .then_with(|| a.service_did.cmp(&b.service_did))
825            .then_with(|| {
826                transport_fingerprint(&a.transport).cmp(&transport_fingerprint(&b.transport))
827            })
828            .then_with(|| af.cmp(bf))
829    });
830    valid.dedup_by(|(af, _), (bf, _)| af == bf);
831    let (selected_fingerprint, selected) = valid.remove(0);
832
833    decisions.sort_by(|a, b| a.candidate_fingerprint.cmp(&b.candidate_fingerprint));
834    let response_verifying_key = VerifyingKey::from_bytes(&selected.response_verifying_key)
835        .map_err(|e| anyhow!("invalid selected response verifying key: {e}"))?;
836    let request_kem_recipient = selected
837        .request_kem_recipient
838        .ok_or_else(|| anyhow!("validated candidate lost request KEM recipient"))?;
839    let expires_at_unix_ms = selected
840        .expires_at_unix_ms
841        .min(selected.accepted_state.expires_at_unix_ms)
842        .min(request_kem_recipient.not_after_unix_ms);
843    Ok(SelectedService {
844        service_name: selected.service_name,
845        service_did: selected.service_did,
846        response_verifying_key,
847        response_ml_dsa65: selected.response_ml_dsa65,
848        response_key_id: selected.response_key_id,
849        request_kem_recipient,
850        transport: selected.transport,
851        capabilities: selected.capabilities,
852        expires_at_unix_ms,
853        evidence: ResolutionEvidence {
854            accepted_state_digest: selected.accepted_state.digest,
855            accepted_state_epoch: selected.accepted_state.epoch,
856            selected_fingerprint,
857            ordered_decisions: decisions,
858        },
859    })
860}
861
862/// Return every validated alternative in the same deterministic order used by
863/// selection. Invalid candidates are discarded independently. Each iteration
864/// reuses the authority-ambiguity gate, so the returned set cannot cross a DID,
865/// accepted head, response key, or KEM recipient.
866#[cfg(test)]
867pub fn select_service_candidates(
868    query: &ServiceQuery,
869    mut candidates: Vec<ServiceCandidate>,
870    now_unix_ms: i64,
871) -> anyhow::Result<Vec<SelectedService>> {
872    let mut ordered = Vec::new();
873    loop {
874        let selected = match select_service_candidate(query, candidates.clone(), now_unix_ms) {
875            Ok(selected) => selected,
876            Err(error) if !ordered.is_empty() && error.to_string().contains("no validated") => {
877                break;
878            }
879            Err(error) => return Err(error),
880        };
881        let fingerprint = selected.evidence.selected_fingerprint.clone();
882        candidates.retain(|candidate| candidate_fingerprint(candidate) != fingerprint);
883        ordered.push(selected);
884    }
885    Ok(ordered)
886}
887
888/// Async endpoint resolver.
889///
890/// Implementations convert a (service_name, socket_kind) pair into a
891/// concrete `TransportConfig`. The async signature supports both local
892/// (in-memory) and remote (network RPC) resolution.
893///
894/// # Implementors
895///
896/// - `EndpointRegistry` — local, in-process resolution (sync internally)
897/// - `DiscoveryService` — authoritative resolution after bootstrap
898/// - `DiscoveryClient` — remote resolution via DiscoveryService RPC (future)
899#[async_trait::async_trait]
900pub trait Resolver: Send + Sync {
901    /// Resolve a service endpoint.
902    ///
903    /// Returns the transport configuration for the given service and socket
904    /// type. Returns `Err` if the service is unknown and no default can be
905    /// generated.
906    async fn resolve(&self, name: &str, kind: SocketKind) -> anyhow::Result<TransportConfig>;
907}
908
909/// Resolver profile names used at service startup.
910///
911/// Profiles make locality an explicit deployment decision. Generated clients
912/// still ask for `(service_name, socket_kind)`; the installed resolver profile
913/// decides whether that name maps to an in-process handle, a same-host Unix
914/// socket, or a network-discovered peer.
915#[derive(Debug, Clone, Copy, PartialEq, Eq)]
916pub enum ResolverProfile {
917    /// Single-process / hermetic-test profile.
918    LocalInproc,
919    /// Local IPC profile.
920    Ipc,
921    /// Multi-host production profile backed by DiscoveryService/PDS records.
922    NetworkDiscovery,
923    /// Native production service traffic. Only Iroh reach is eligible.
924    NativeIrohRequired,
925    /// Public browser edge. Only QUIC/WebTransport reach is eligible.
926    BrowserWebTransport,
927}
928
929/// Network profile wrapper for a DiscoveryService/PDS-backed resolver.
930///
931/// The wrapped resolver owns service discovery. This wrapper enforces the
932/// network-profile invariant: same-host endpoints (`inproc`, `ipc`,
933/// `systemd-fd`) are not valid routable service reach.
934pub struct NetworkDiscoveryResolver {
935    inner: Arc<dyn Resolver>,
936}
937
938impl NetworkDiscoveryResolver {
939    pub fn new(inner: Arc<dyn Resolver>) -> Self {
940        Self { inner }
941    }
942}
943
944#[async_trait::async_trait]
945impl Resolver for NetworkDiscoveryResolver {
946    async fn resolve(&self, name: &str, kind: SocketKind) -> anyhow::Result<TransportConfig> {
947        let transport = self.inner.resolve(name, kind).await?;
948        match &transport.endpoint {
949            EndpointType::Inproc { .. }
950            | EndpointType::Ipc { .. }
951            | EndpointType::SystemdFd { .. } => Err(anyhow!(
952                "network-discovery resolver returned same-host endpoint for service '{name}' ({kind:?})"
953            )),
954            EndpointType::Iroh { .. } => Ok(transport),
955            EndpointType::Quic { .. } => Err(anyhow!(
956                "native Iroh resolver returned QUIC/WebTransport reach for service '{name}' ({kind:?})"
957            )),
958        }
959    }
960}
961
962// ============================================================================
963// Pluggable global resolver (replaceable)
964// ============================================================================
965
966static GLOBAL_RESOLVER: RwLock<Option<Arc<dyn Resolver>>> = RwLock::new(None);
967#[cfg(test)]
968static GLOBAL_SERVICE_RESOLVER: RwLock<Option<Arc<dyn ServiceResolver>>> = RwLock::new(None);
969
970/// Install the identity-bound production resolver after explicit Discovery
971/// bootstrap. This is intentionally separate from the legacy endpoint-only
972/// resolver so `TransportConfig` never becomes an authority object.
973#[cfg(test)]
974pub fn set_global_service(resolver: Arc<dyn ServiceResolver>) {
975    *GLOBAL_SERVICE_RESOLVER.write() = Some(resolver);
976}
977
978/// Clone the installed identity-bound resolver without retaining a lock guard.
979#[cfg(test)]
980pub fn try_global_service() -> Option<Arc<dyn ServiceResolver>> {
981    GLOBAL_SERVICE_RESOLVER.read().clone()
982}
983
984/// Set the global resolver.
985///
986/// Can be called multiple times — each call replaces the previous resolver.
987/// During bootstrap, `registry::init()` installs an explicit local resolver
988/// profile. A networked deployment can replace that with a
989/// [`NetworkDiscoveryResolver`] wrapping DiscoveryService or a DiscoveryClient.
990///
991/// # Example
992///
993/// ```ignore
994/// // Bootstrap: registry installs itself
995/// hyprstream_rpc::registry::init(mode, runtime_dir);
996///
997/// // After DiscoveryService starts, it replaces the bootstrap resolver:
998/// hyprstream_rpc::resolver::set_global(discovery_service.clone());
999/// ```
1000pub fn set_global(resolver: Arc<dyn Resolver>) {
1001    *GLOBAL_RESOLVER.write() = Some(resolver);
1002}
1003
1004/// Get the global resolver (non-panicking).
1005///
1006/// Returns `None` before `set_global()` has been called.
1007pub fn try_global() -> Option<Arc<dyn Resolver>> {
1008    GLOBAL_RESOLVER.read().clone()
1009}
1010
1011/// Get the global resolver.
1012///
1013/// # Panics
1014///
1015/// Panics if `set_global()` has not been called.
1016#[deprecated(note = "use try_global() instead for graceful degradation (D9)")]
1017pub fn global() -> Arc<dyn Resolver> {
1018    #[allow(clippy::expect_used)] // Intentional panic for programming error
1019    GLOBAL_RESOLVER
1020        .read()
1021        .clone()
1022        .expect("Global resolver not initialized — call resolver::set_global() first")
1023}
1024
1025#[cfg(test)]
1026#[allow(clippy::expect_used, clippy::unwrap_used)]
1027mod tests {
1028    use super::*;
1029    use std::sync::atomic::{AtomicUsize, Ordering};
1030
1031    fn candidate(tag: u8, transport: TransportConfig) -> ServiceCandidate {
1032        let ed = crate::crypto::SigningKey::from_bytes(&[tag; 32])
1033            .verifying_key()
1034            .to_bytes();
1035        let (_pq_sk, pq_vk) = crate::crypto::pq::ml_dsa_generate_keypair();
1036        let pq = crate::crypto::pq::ml_dsa_vk_bytes(&pq_vk);
1037        let kem = crate::crypto::hybrid_kem::generate_recipient(
1038            crate::crypto::hybrid_kem::SuiteId::HyKemX25519MlKem768,
1039        )
1040        .unwrap_or_else(|e| panic!("test KEM generation failed: {e}"))
1041        .public();
1042        let did = Did::from(format!("did:at9p:service-{tag}"));
1043        ServiceCandidate {
1044            service_name: "model".to_owned(),
1045            service_did: did.clone(),
1046            response_verifying_key: ed,
1047            response_ml_dsa65: pq.clone(),
1048            response_key_id: format!("{did}#response-{tag}"),
1049            request_kem_recipient: Some(AnchoredKemRecipient {
1050                key_id: format!("{did}#kem-{tag}"),
1051                recipient: kem,
1052                not_after_unix_ms: 20_000,
1053            }),
1054            transport,
1055            capabilities: ["hyprstream-rpc/1".to_owned()].into_iter().collect(),
1056            accepted_state: AcceptedStateEvidence {
1057                service_did: did,
1058                digest: [tag; 64],
1059                epoch: u64::from(tag),
1060                expires_at_unix_ms: 20_000,
1061                response_ed25519: ed,
1062                response_ml_dsa65: pq,
1063            },
1064            source_signer: ed,
1065            expires_at_unix_ms: 20_000,
1066        }
1067    }
1068
1069    fn network_query() -> ServiceQuery {
1070        ServiceQuery::network("model").unwrap_or_else(|e| panic!("test query must be valid: {e}"))
1071    }
1072
1073    #[test]
1074    fn identity_bound_selection_positive_control() {
1075        let candidate = candidate(7, TransportConfig::iroh([9; 32], Vec::new(), None));
1076        let expected_response = candidate.response_verifying_key;
1077        let selected = select_service_candidate(&network_query(), vec![candidate], 1_000)
1078            .unwrap_or_else(|e| panic!("valid candidate rejected: {e}"));
1079        assert_eq!(selected.service_did.as_str(), "did:at9p:service-7");
1080        assert_eq!(
1081            selected.response_verifying_key.to_bytes(),
1082            expected_response
1083        );
1084        assert!(selected.request_kem_recipient.key_id.ends_with("#kem-7"));
1085        assert_eq!(selected.evidence.accepted_state_epoch, 7);
1086        selected
1087            .crypto_stores()
1088            .unwrap_or_else(|e| panic!("selected exact crypto stores invalid: {e}"));
1089    }
1090
1091    struct AlwaysAdvancedResolver {
1092        snapshot: SelectedService,
1093        resolves: AtomicUsize,
1094        checks: AtomicUsize,
1095    }
1096
1097    #[async_trait::async_trait]
1098    impl ServiceResolver for AlwaysAdvancedResolver {
1099        async fn resolve_service(&self, _query: ServiceQuery) -> anyhow::Result<SelectedService> {
1100            self.resolves.fetch_add(1, Ordering::SeqCst);
1101            Ok(self.snapshot.clone())
1102        }
1103
1104        async fn ensure_current(&self, _resolved: &SelectedService) -> anyhow::Result<()> {
1105            self.checks.fetch_add(1, Ordering::SeqCst);
1106            anyhow::bail!("accepted state advanced")
1107        }
1108    }
1109
1110    #[tokio::test]
1111    async fn lazy_first_send_re_resolves_once_and_refuses_before_transport() {
1112        let snapshot = select_service_candidate(
1113            &network_query(),
1114            vec![candidate(
1115                8,
1116                TransportConfig::iroh([8; 32], Vec::new(), None),
1117            )],
1118            1_000,
1119        )
1120        .expect("fixture snapshot");
1121        let resolver = Arc::new(AlwaysAdvancedResolver {
1122            snapshot,
1123            resolves: AtomicUsize::new(0),
1124            checks: AtomicUsize::new(0),
1125        });
1126        let signing = crate::crypto::SigningKey::from_bytes(&[0x41; 32]);
1127        let client = ResolvedRpcClient::new("model", signing, None, resolver.clone())
1128            .expect("resolved lazy client");
1129        let error = client
1130            .call(vec![1, 2, 3])
1131            .await
1132            .expect_err("advanced state dialed");
1133        assert!(
1134            error.to_string().contains("remained invalid"),
1135            "unexpected refusal: {error:#}"
1136        );
1137        assert_eq!(resolver.resolves.load(Ordering::SeqCst), 2);
1138        assert_eq!(resolver.checks.load(Ordering::SeqCst), 2);
1139    }
1140
1141    #[test]
1142    fn only_explicit_pre_dispatch_errors_are_retry_safe() {
1143        let ordinary = anyhow!("service rejected request after dispatch");
1144        assert!(!crate::transport_traits::is_pre_dispatch_transport_error(
1145            &ordinary
1146        ));
1147        let marked = anyhow::Error::new(crate::transport_traits::PreDispatchTransportError::new(
1148            anyhow!("dial refused"),
1149        ));
1150        assert!(crate::transport_traits::is_pre_dispatch_transport_error(
1151            &marked
1152        ));
1153    }
1154
1155    #[test]
1156    fn required_properties_fail_before_dial() {
1157        let query = network_query();
1158        assert!(select_service_candidate(&query, Vec::new(), 1_000).is_err());
1159
1160        let base = candidate(3, TransportConfig::iroh([3; 32], Vec::new(), None));
1161        let mut cases = Vec::new();
1162        let mut expired = base.clone();
1163        expired.expires_at_unix_ms = 999;
1164        cases.push(expired);
1165        let mut expired_state = base.clone();
1166        expired_state.accepted_state.expires_at_unix_ms = 999;
1167        cases.push(expired_state);
1168        let mut missing_capability = base.clone();
1169        missing_capability.capabilities.clear();
1170        cases.push(missing_capability);
1171        let mut wrong_response = base.clone();
1172        wrong_response.response_verifying_key = [8; 32];
1173        cases.push(wrong_response);
1174        let mut wrong_source = base.clone();
1175        wrong_source.source_signer = [8; 32];
1176        cases.push(wrong_source);
1177        let mut omitted_pq = base.clone();
1178        omitted_pq.response_ml_dsa65.clear();
1179        omitted_pq.accepted_state.response_ml_dsa65.clear();
1180        cases.push(omitted_pq);
1181        let mut missing_kem = base.clone();
1182        missing_kem.request_kem_recipient = None;
1183        cases.push(missing_kem);
1184        let mut expired_kem = base.clone();
1185        expired_kem
1186            .request_kem_recipient
1187            .as_mut()
1188            .expect("fixture KEM")
1189            .not_after_unix_ms = 999;
1190        cases.push(expired_kem);
1191        let mut omitted_kem_component = base.clone();
1192        omitted_kem_component
1193            .request_kem_recipient
1194            .as_mut()
1195            .expect("fixture KEM")
1196            .recipient
1197            .eks
1198            .pop();
1199        cases.push(omitted_kem_component);
1200        let mut cross_service_kem = base.clone();
1201        cross_service_kem
1202            .request_kem_recipient
1203            .as_mut()
1204            .expect("fixture KEM")
1205            .key_id = "did:at9p:other#kem".to_owned();
1206        cases.push(cross_service_kem);
1207        let mut wrong_identity = base.clone();
1208        wrong_identity.service_did = Did::from("did:at9p:other");
1209        cases.push(wrong_identity);
1210        let mut reach_only = base.clone();
1211        reach_only.service_did = Did::default();
1212        reach_only.accepted_state.service_did = Did::default();
1213        cases.push(reach_only);
1214        let mut local = base;
1215        local.transport = TransportConfig::inproc("hyprstream/model");
1216        cases.push(local);
1217
1218        for invalid in cases {
1219            assert!(
1220                select_service_candidate(&query, vec![invalid], 1_000).is_err(),
1221                "invalid candidate reached dial selection"
1222            );
1223        }
1224    }
1225
1226    #[test]
1227    fn candidate_permutations_select_identically() {
1228        let mut a = candidate(1, TransportConfig::iroh([1; 32], Vec::new(), None));
1229        a.capabilities.extend(["x".to_owned(), "y".to_owned()]);
1230        let mut b = a.clone();
1231        b.capabilities.remove("x");
1232        b.capabilities.remove("y");
1233        b.capabilities.insert("x\0y".to_owned());
1234        assert_ne!(candidate_fingerprint(&a), candidate_fingerprint(&b));
1235        b.transport = TransportConfig::iroh([2; 32], Vec::new(), None);
1236        let first = select_service_candidate(&network_query(), vec![a.clone(), b.clone()], 1_000)
1237            .unwrap_or_else(|e| panic!("selection failed: {e}"));
1238        let second = select_service_candidate(&network_query(), vec![b, a], 1_000)
1239            .unwrap_or_else(|e| panic!("selection failed: {e}"));
1240        assert_eq!(first.service_did, second.service_did);
1241        assert_eq!(first.transport, second.transport);
1242        assert_eq!(first.response_verifying_key, second.response_verifying_key);
1243        assert_eq!(first.request_kem_recipient, second.request_kem_recipient);
1244        assert_eq!(first.evidence, second.evidence);
1245    }
1246
1247    #[test]
1248    fn distinct_valid_identities_are_ambiguous() {
1249        let a = candidate(1, TransportConfig::iroh([1; 32], Vec::new(), None));
1250        let b = candidate(2, TransportConfig::iroh([2; 32], Vec::new(), None));
1251        let error = select_service_candidate(&network_query(), vec![a, b], 1_000)
1252            .expect_err("distinct service authorities were ranked as interchangeable");
1253        assert!(error.to_string().contains("ambiguous"));
1254    }
1255
1256    #[test]
1257    fn explicit_local_profiles_accept_only_their_local_reach() {
1258        let inproc_query = ServiceQuery::new(
1259            "model",
1260            ["hyprstream-rpc/1".to_owned()],
1261            ResolverProfile::LocalInproc,
1262            1,
1263        )
1264        .expect("local query");
1265        assert!(select_service_candidate(
1266            &inproc_query,
1267            vec![candidate(4, TransportConfig::inproc("hyprstream/model"))],
1268            1_000,
1269        )
1270        .is_ok());
1271        assert!(select_service_candidate(
1272            &inproc_query,
1273            vec![candidate(4, TransportConfig::ipc("/tmp/model.sock"))],
1274            1_000,
1275        )
1276        .is_err());
1277
1278        let ipc_query = ServiceQuery::new(
1279            "model",
1280            ["hyprstream-rpc/1".to_owned()],
1281            ResolverProfile::Ipc,
1282            1,
1283        )
1284        .expect("IPC query");
1285        assert!(select_service_candidate(
1286            &ipc_query,
1287            vec![candidate(5, TransportConfig::ipc("/tmp/model.sock"))],
1288            1_000,
1289        )
1290        .is_ok());
1291    }
1292
1293    #[tokio::test]
1294    async fn retries_are_bounded_to_validated_order() {
1295        let first_candidate = candidate(1, TransportConfig::iroh([1; 32], Vec::new(), None));
1296        let mut second_candidate = first_candidate.clone();
1297        second_candidate.transport = TransportConfig::iroh([2; 32], Vec::new(), None);
1298        let first = select_service_candidate(&network_query(), vec![first_candidate], 1_000)
1299            .unwrap_or_else(|e| panic!("selection failed: {e}"));
1300        let second = select_service_candidate(&network_query(), vec![second_candidate], 1_000)
1301            .unwrap_or_else(|e| panic!("selection failed: {e}"));
1302        let seen = Arc::new(parking_lot::Mutex::new(Vec::new()));
1303        let observed = Arc::clone(&seen);
1304        let result: anyhow::Result<()> =
1305            retry_validated_candidates(vec![first, second.clone()], 1, move |resolved| {
1306                observed.lock().push(resolved.service_did.clone());
1307                std::future::ready(Err(anyhow!("sentinel dial failure")))
1308            })
1309            .await;
1310        assert!(result.is_err());
1311        assert_eq!(seen.lock().len(), 1);
1312
1313        let other = select_service_candidate(
1314            &network_query(),
1315            vec![candidate(
1316                2,
1317                TransportConfig::iroh([3; 32], Vec::new(), None),
1318            )],
1319            1_000,
1320        )
1321        .unwrap_or_else(|e| panic!("selection failed: {e}"));
1322        let crossed: anyhow::Result<()> =
1323            retry_validated_candidates(vec![second, other], 2, |_| std::future::ready(Ok(())))
1324                .await;
1325        assert!(crossed.is_err());
1326    }
1327
1328    struct StaticResolver(TransportConfig);
1329
1330    #[async_trait::async_trait]
1331    impl Resolver for StaticResolver {
1332        async fn resolve(&self, _name: &str, _kind: SocketKind) -> anyhow::Result<TransportConfig> {
1333            Ok(self.0.clone())
1334        }
1335    }
1336
1337    #[tokio::test]
1338    async fn network_discovery_resolver_rejects_inproc_reach() {
1339        let resolver = NetworkDiscoveryResolver::new(Arc::new(StaticResolver(
1340            TransportConfig::inproc("hyprstream/policy"),
1341        )));
1342
1343        let err = match resolver.resolve("policy", SocketKind::Rep).await {
1344            Ok(endpoint) => panic!("network resolver accepted local endpoint: {endpoint:?}"),
1345            Err(err) => err,
1346        };
1347        assert!(
1348            err.to_string().contains("same-host endpoint"),
1349            "unexpected error: {err}"
1350        );
1351    }
1352
1353    #[tokio::test]
1354    async fn network_discovery_resolver_rejects_same_host_reach() {
1355        for local in [
1356            TransportConfig::ipc("/run/hyprstream/policy.sock"),
1357            TransportConfig::systemd_fd(3, "/run/hyprstream/policy.sock"),
1358        ] {
1359            let resolver = NetworkDiscoveryResolver::new(Arc::new(StaticResolver(local)));
1360            let err = match resolver.resolve("policy", SocketKind::Rep).await {
1361                Ok(endpoint) => {
1362                    panic!("network resolver accepted same-host endpoint: {endpoint:?}")
1363                }
1364                Err(err) => err,
1365            };
1366            assert!(
1367                err.to_string().contains("same-host endpoint"),
1368                "unexpected error: {err}"
1369            );
1370        }
1371    }
1372
1373    #[tokio::test]
1374    async fn native_iroh_resolver_rejects_quic_reach() {
1375        let addr = "127.0.0.1:9443"
1376            .parse()
1377            .unwrap_or_else(|err| panic!("test socket address must parse: {err}"));
1378        let quic = TransportConfig::quic(addr, "policy.local");
1379        let resolver = NetworkDiscoveryResolver::new(Arc::new(StaticResolver(quic.clone())));
1380
1381        let error = resolver
1382            .resolve("policy", SocketKind::Rep)
1383            .await
1384            .expect_err("native Iroh resolver must reject QUIC/WebTransport reach");
1385        assert!(error.to_string().contains("QUIC/WebTransport"));
1386    }
1387
1388    #[tokio::test]
1389    async fn network_discovery_resolver_accepts_iroh_reach() {
1390        let iroh = TransportConfig::iroh([7; 32], Vec::new(), None);
1391        let resolver = NetworkDiscoveryResolver::new(Arc::new(StaticResolver(iroh.clone())));
1392
1393        let endpoint = resolver
1394            .resolve("policy", SocketKind::Rep)
1395            .await
1396            .unwrap_or_else(|err| panic!("network resolver rejected iroh endpoint: {err}"));
1397        assert_eq!(endpoint, iroh);
1398    }
1399}