ma_core/ipfs/
gateway_resolver.rs

1//! DID document resolution over the IPFS gateway pool.
2//!
3//! Thin composition layer: [`GatewayPool`] does the HTTP work, a
4//! [`TtlCache`] remembers outcomes, and this module only knows how to turn
5//! gateway bytes into validated [`Document`]s.
6
7use super::gateway::GatewayPool;
8use super::ttl_cache::{Cached, TtlCache};
9use crate::Document;
10use async_trait::async_trait;
11use web_time::Duration;
12
13/// Trait for resolving a DID to its DID document.
14///
15/// Ship with `IpfsGatewayResolver` for HTTP gateway resolution.
16/// Implement this trait for custom resolution strategies.
17#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
18#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
19pub trait DidDocumentResolver: Send + Sync {
20    async fn resolve(&self, did: &str) -> crate::error::Result<Document>;
21
22    /// Update resolver cache TTLs at runtime.
23    ///
24    /// Default implementation is a no-op for resolvers without mutable cache policy.
25    fn set_cache_ttls(&self, _positive_ttl: Duration, _negative_ttl: Duration) {}
26
27    /// Return current resolver cache TTLs when supported.
28    fn cache_ttls(&self) -> Option<(Duration, Duration)> {
29        None
30    }
31}
32
33/// Trait for resolving an `/ipns/<name>` path to its current `/ipfs/<cid>` path.
34///
35/// Implemented by [`IpfsGatewayResolver`] (HTTP gateways); alternative
36/// backends (e.g. a local Kubo RPC) can implement it too.
37#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
38#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
39pub trait IpnsPathResolver: Send + Sync {
40    async fn resolve_ipns_path(&self, path: &str) -> crate::error::Result<String>;
41}
42
43/// Resolves DID documents via an IPFS/IPNS HTTP gateway.
44///
45/// The gateway must serve DID documents at `/ipns/<key-id>`.
46/// Cached document bytes and negative outcomes expire on independent TTLs.
47pub struct IpfsGatewayResolver {
48    pool: GatewayPool,
49    cache: TtlCache<Vec<u8>>,
50}
51
52impl Default for IpfsGatewayResolver {
53    /// Build a local-first resolver for development and native runtimes.
54    fn default() -> Self {
55        Self::from_pool(GatewayPool::default())
56    }
57}
58
59impl From<GatewayPool> for IpfsGatewayResolver {
60    fn from(pool: GatewayPool) -> Self {
61        Self::from_pool(pool)
62    }
63}
64
65impl IpfsGatewayResolver {
66    /// Build a public-gateway resolver with no localhost probing.
67    #[must_use]
68    pub fn public_default() -> Self {
69        Self::from_pool(GatewayPool::public_default())
70    }
71
72    /// Build a resolver using the caller-provided primary gateway followed by
73    /// the standard public fallbacks. Localhost is used only if `gateway_url`
74    /// itself points at localhost.
75    #[must_use]
76    pub fn new(gateway_url: impl Into<String>) -> Self {
77        Self::from_pool(GatewayPool::new(gateway_url))
78    }
79
80    /// Build a local-first resolver: localhost, then the caller-provided
81    /// primary gateway, then the standard public fallbacks.
82    #[must_use]
83    pub fn local_first(gateway_url: impl Into<String>) -> Self {
84        Self::from_pool(GatewayPool::local_first(gateway_url))
85    }
86
87    fn from_pool(pool: GatewayPool) -> Self {
88        Self {
89            pool,
90            cache: TtlCache::new(Duration::from_mins(1), Duration::from_secs(10)),
91        }
92    }
93
94    /// The underlying gateway pool, for generic content fetches.
95    #[must_use]
96    pub fn pool(&self) -> &GatewayPool {
97        &self.pool
98    }
99
100    #[must_use]
101    pub fn with_cache_ttls(self, positive_ttl: Duration, negative_ttl: Duration) -> Self {
102        self.cache.set_ttls(positive_ttl, negative_ttl);
103        self
104    }
105
106    /// Override the base per-gateway failure cooldown. The cooldown
107    /// escalates Fibonacci-style per consecutive failure and resets on
108    /// success. `Duration::ZERO` disables cooldowns entirely.
109    #[must_use]
110    pub fn with_base_cooldown(mut self, cooldown: Duration) -> Self {
111        self.pool = self.pool.with_base_cooldown(cooldown);
112        self
113    }
114
115    /// Override the per-request timeout (default 6 seconds). Covers the
116    /// whole request, connection through body transfer.
117    #[must_use]
118    pub fn with_request_timeout(self, timeout: Duration) -> Self {
119        self.pool.set_request_timeout(Some(timeout));
120        self
121    }
122
123    /// Update the per-request timeout at runtime.
124    /// Pass `None` to revert to the 6-second built-in default.
125    pub fn set_request_timeout(&self, timeout: Option<Duration>) {
126        self.pool.set_request_timeout(timeout);
127    }
128
129    /// Resolve an `/ipns/<name>` reference to its current `/ipfs/<cid>` path.
130    pub async fn resolve_ipns_path(&self, path: &str) -> crate::error::Result<String> {
131        self.pool.resolve_ipns_path(path).await
132    }
133
134    fn cached_result(cached: Cached<Vec<u8>>, did: String) -> crate::error::Result<Document> {
135        match cached {
136            Cached::Hit(body) => {
137                parse_document_bytes(&body).map_err(|detail| crate::error::Error::Resolution {
138                    did,
139                    detail: format!("cached document parse failed: {detail}"),
140                })
141            }
142            Cached::Miss(detail) => Err(crate::error::Error::Resolution { did, detail }),
143        }
144    }
145}
146
147#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
148#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
149impl DidDocumentResolver for IpfsGatewayResolver {
150    async fn resolve(&self, did: &str) -> crate::error::Result<Document> {
151        let parsed = crate::Did::try_from(did).map_err(crate::error::Error::Validation)?;
152        let did_key = did.to_string();
153
154        if let Some(cached) = self.cache.read(&did_key) {
155            return Self::cached_result(cached, did_key);
156        }
157
158        let resolve_lock = self.cache.lock_for(&did_key);
159        let _resolve_guard = resolve_lock.lock().await;
160
161        // Another caller may have populated the cache while this caller waited
162        // for the per-DID lock.
163        if let Some(cached) = self.cache.read(&did_key) {
164            self.cache.release_lock(&did_key, &resolve_lock);
165            return Self::cached_result(cached, did_key);
166        }
167
168        let path = format!("/ipns/{}", parsed.ipns);
169        let fetched = self
170            .pool
171            .fetch(&path, Some("application/vnd.ipld.dag-cbor"), |body| {
172                parse_document_bytes(body)
173                    .map(|document| (document, body.to_vec()))
174                    .map_err(|detail| format!("invalid DID document: {detail}"))
175            })
176            .await;
177
178        match fetched {
179            Ok((document, body)) => {
180                self.cache.write_hit(did_key.clone(), body);
181                self.cache.release_lock(&did_key, &resolve_lock);
182                Ok(document)
183            }
184            Err(detail) => {
185                tracing::warn!(did = %did_key, error = %detail, "DID document resolve failed");
186                self.cache.write_miss(did_key.clone(), detail.clone());
187                self.cache.release_lock(&did_key, &resolve_lock);
188                Err(crate::error::Error::Resolution {
189                    did: did_key,
190                    detail,
191                })
192            }
193        }
194    }
195
196    fn set_cache_ttls(&self, positive_ttl: Duration, negative_ttl: Duration) {
197        self.cache.set_ttls(positive_ttl, negative_ttl);
198    }
199
200    fn cache_ttls(&self) -> Option<(Duration, Duration)> {
201        Some((self.cache.positive_ttl(), self.cache.negative_ttl()))
202    }
203}
204
205#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
206#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
207impl IpnsPathResolver for IpfsGatewayResolver {
208    async fn resolve_ipns_path(&self, path: &str) -> crate::error::Result<String> {
209        self.pool.resolve_ipns_path(path).await
210    }
211}
212
213fn parse_document_bytes(bytes: &[u8]) -> std::result::Result<Document, String> {
214    // Try DAG-CBOR first (canonical wire format; what dweb.link and Kubo return
215    // when the client sends Accept: application/vnd.ipld.dag-cbor).
216    if let Ok(doc) = Document::decode(bytes) {
217        return Ok(doc);
218    }
219    // Fallback: some gateways (e.g. a local Kubo that ignores the Accept header)
220    // may return DAG-JSON or plain JSON.
221    serde_json::from_slice::<Document>(bytes)
222        .map_err(|json_err| format!("CBOR decode failed and JSON fallback also failed: {json_err}"))
223}
224
225#[cfg(test)]
226mod tests {
227    use super::parse_document_bytes;
228    use crate::generate_identity_from_secret;
229
230    #[test]
231    fn parses_dag_cbor_documents() {
232        let identity = generate_identity_from_secret([7u8; 32]).expect("identity");
233        let cbor = identity.document.encode().expect("cbor");
234        let parsed = parse_document_bytes(&cbor).expect("parsed cbor");
235        assert_eq!(parsed, identity.document);
236    }
237
238    #[test]
239    fn rejects_non_document_payloads() {
240        let err = parse_document_bytes(b"<html>nope</html>").expect_err("invalid payload");
241        assert!(err.contains("CBOR decode failed"));
242    }
243
244    #[test]
245    fn parses_json_fallback_when_cbor_fails() {
246        let identity = generate_identity_from_secret([5u8; 32]).expect("identity");
247        let json = serde_json::to_vec(&identity.document).expect("json serialize");
248        let parsed = parse_document_bytes(&json).expect("JSON fallback should succeed");
249        assert_eq!(parsed, identity.document);
250    }
251
252    #[test]
253    fn resolver_constructors_delegate_to_pool() {
254        use super::IpfsGatewayResolver;
255        let resolver = IpfsGatewayResolver::new("https://example.test/ipfs");
256        assert_eq!(
257            resolver.pool().gateways(),
258            [
259                "https://example.test/ipfs/".to_string(),
260                "https://dweb.link/".to_string(),
261                "https://4everland.io/".to_string(),
262            ]
263        );
264    }
265}
ma_core/ipfs/gateway_resolver.rs

ma_core/ipfs/
gateway_resolver.rs
