helia_interface/
routing.rs

1//! Routing interface for peer and content discovery
2
3use std::time::Duration;
4
5use async_trait::async_trait;
6use cid::Cid;
7use libp2p::{Multiaddr, PeerId};
8use serde::{Deserialize, Serialize};
9
10use crate::{AbortOptions, AwaitIterable, HeliaError, ProgressOptions};
11
12/// Options for routing operations
13#[derive(Debug, Clone)]
14pub struct RoutingOptions {
15    /// Abort options
16    pub abort: AbortOptions,
17    /// Progress options
18    pub progress: ProgressOptions<()>,
19    /// Whether to use the network for lookups (default: true)
20    pub use_network: bool,
21    /// Whether to use cached values (default: true)
22    pub use_cache: bool,
23    /// Whether to perform validation (default: true)
24    pub validate: bool,
25}
26
27impl Default for RoutingOptions {
28    fn default() -> Self {
29        Self {
30            abort: AbortOptions::default(),
31            progress: ProgressOptions::default(),
32            use_network: true,
33            use_cache: true,
34            validate: true,
35        }
36    }
37}
38
39/// Information about a peer
40#[derive(Debug, Clone, Serialize, Deserialize)]
41pub struct PeerInfo {
42    /// The peer's ID
43    pub id: PeerId,
44    /// Known multiaddresses for the peer
45    pub multiaddrs: Vec<Multiaddr>,
46    /// Protocols supported by the peer
47    pub protocols: Vec<String>,
48}
49
50/// A provider can supply content for a CID
51#[derive(Debug, Clone, Serialize, Deserialize)]
52pub struct Provider {
53    /// Peer information
54    #[serde(flatten)]
55    pub peer_info: PeerInfo,
56    /// Transport methods available for retrieving content
57    pub transport_methods: Vec<TransportMethod>,
58}
59
60/// Methods available for content transport
61#[derive(Debug, Clone, Serialize, Deserialize)]
62#[serde(rename_all = "kebab-case")]
63pub enum TransportMethod {
64    /// Content available over Bitswap protocol
65    Bitswap,
66    /// Content available over HTTP
67    Http,
68    /// Content available over libp2p streams
69    Libp2pStream,
70    /// Custom transport method
71    Custom(String),
72}
73
74/// Options for finding providers
75#[derive(Debug, Clone, Default)]
76pub struct FindProvidersOptions {
77    /// Routing options
78    pub routing: RoutingOptions,
79}
80
81/// Options for providing content
82#[derive(Debug, Clone, Default)]
83pub struct ProvideOptions {
84    /// Routing options
85    pub routing: RoutingOptions,
86}
87
88/// Options for finding peers
89#[derive(Debug, Clone, Default)]
90pub struct FindPeersOptions {
91    /// Routing options
92    pub routing: RoutingOptions,
93}
94
95/// Options for getting peer info
96#[derive(Debug, Clone, Default)]
97pub struct GetOptions {
98    /// Routing options
99    pub routing: RoutingOptions,
100}
101
102/// Options for putting records
103#[derive(Debug, Clone, Default)]
104pub struct PutOptions {
105    /// Routing options
106    pub routing: RoutingOptions,
107}
108
109/// A routing record
110#[derive(Debug, Clone, Serialize, Deserialize)]
111pub struct RoutingRecord {
112    /// The record key
113    pub key: Vec<u8>,
114    /// The record value
115    pub value: Vec<u8>,
116    /// When the record was created
117    pub time_received: Option<std::time::SystemTime>,
118    /// TTL for the record
119    pub ttl: Option<Duration>,
120}
121
122/// Routing interface for peer and content discovery
123#[async_trait]
124pub trait Routing: Send + Sync {
125    /// Find providers for a given CID
126    async fn find_providers(
127        &self,
128        cid: &Cid,
129        options: Option<FindProvidersOptions>,
130    ) -> Result<AwaitIterable<Provider>, HeliaError>;
131
132    /// Announce that this node can provide content for a CID
133    async fn provide(&self, cid: &Cid, options: Option<ProvideOptions>) -> Result<(), HeliaError>;
134
135    /// Find peers in the routing system
136    async fn find_peers(
137        &self,
138        peer_id: &PeerId,
139        options: Option<FindPeersOptions>,
140    ) -> Result<AwaitIterable<PeerInfo>, HeliaError>;
141
142    /// Get a record from the routing system
143    async fn get(
144        &self,
145        key: &[u8],
146        options: Option<GetOptions>,
147    ) -> Result<Option<RoutingRecord>, HeliaError>;
148
149    /// Put a record into the routing system
150    async fn put(
151        &self,
152        key: &[u8],
153        value: &[u8],
154        options: Option<PutOptions>,
155    ) -> Result<(), HeliaError>;
156}
helia_interface/routing.rs

helia_interface/
routing.rs
