hashtree_resolver/
traits.rs

1//! Core traits for root resolvers
2
3use async_trait::async_trait;
4use hashtree_core::Cid;
5use thiserror::Error;
6use tokio::sync::mpsc;
7
8/// Errors that can occur during resolution
9#[derive(Error, Debug)]
10pub enum ResolverError {
11    #[error("Invalid key format: {0}")]
12    InvalidKey(String),
13
14    #[error("Network error: {0}")]
15    Network(String),
16
17    #[error("Not authorized to publish")]
18    NotAuthorized,
19
20    #[error("Resolver stopped")]
21    Stopped,
22
23    #[error("Other error: {0}")]
24    Other(String),
25}
26
27/// Entry in a resolver list
28#[derive(Debug, Clone)]
29pub struct ResolverEntry {
30    pub key: String,
31    pub cid: Cid,
32}
33
34/// RootResolver - Maps human-readable keys to content identifiers (Cid)
35///
36/// This abstraction allows different backends (Nostr, DNS, HTTP, local storage)
37/// to provide mutable pointers to immutable content-addressed data.
38///
39/// The Cid contains:
40/// - hash: content hash (always present)
41/// - key: optional decryption key (for CHK encrypted content)
42/// - size: content size
43///
44/// Unlike the TypeScript version which uses callbacks, this Rust version uses
45/// channels which are more idiomatic for async Rust.
46#[async_trait]
47pub trait RootResolver: Send + Sync {
48    /// Resolve a key to its current Cid (one-shot)
49    ///
50    /// Returns None if the key doesn't exist or can't be resolved.
51    /// For shared content, pass the share_secret to decrypt the encrypted_key.
52    async fn resolve(&self, key: &str) -> Result<Option<Cid>, ResolverError>;
53
54    /// Resolve with a share secret (for encrypted_key decryption)
55    async fn resolve_shared(&self, key: &str, share_secret: &[u8; 32]) -> Result<Option<Cid>, ResolverError> {
56        let _ = share_secret;
57        self.resolve(key).await
58    }
59
60    /// Subscribe to Cid changes for a key.
61    ///
62    /// Returns a channel receiver that will receive the current value immediately,
63    /// then subsequent updates. The channel is closed when the subscription ends.
64    ///
65    /// To unsubscribe, simply drop the receiver.
66    async fn subscribe(&self, key: &str) -> Result<mpsc::Receiver<Option<Cid>>, ResolverError>;
67
68    /// Publish/update a Cid (optional - only for writable backends)
69    ///
70    /// Returns true if published successfully.
71    async fn publish(&self, key: &str, cid: &Cid) -> Result<bool, ResolverError> {
72        let _ = (key, cid);
73        Err(ResolverError::NotAuthorized)
74    }
75
76    /// Publish with encrypted key for sharing
77    ///
78    /// The key is encrypted with share_secret, allowing anyone with the secret to decrypt.
79    async fn publish_shared(&self, key: &str, cid: &Cid, share_secret: &[u8; 32]) -> Result<bool, ResolverError> {
80        let _ = (key, cid, share_secret);
81        Err(ResolverError::NotAuthorized)
82    }
83
84    /// List all keys matching a prefix (one-shot)
85    ///
86    /// Returns array of matching keys with their current Cids.
87    async fn list(&self, prefix: &str) -> Result<Vec<ResolverEntry>, ResolverError> {
88        let _ = prefix;
89        Ok(vec![])
90    }
91
92    /// Subscribe to list changes for a prefix.
93    ///
94    /// Returns a channel receiver that will receive the current list immediately,
95    /// then the full updated list on each add/remove/update.
96    async fn subscribe_list(
97        &self,
98        prefix: &str,
99    ) -> Result<mpsc::Receiver<Vec<ResolverEntry>>, ResolverError> {
100        let _ = prefix;
101        Err(ResolverError::Other("Not implemented".into()))
102    }
103
104    /// Stop the resolver and clean up resources
105    async fn stop(&self) -> Result<(), ResolverError> {
106        Ok(())
107    }
108}
hashtree_resolver/traits.rs

hashtree_resolver/
traits.rs
