Struct hermes_ipfs::Ipfs

pub struct Ipfs {
    pub(crate) span: Span,
    pub(crate) repo: Repo,
    pub(crate) key: Keypair,
    pub(crate) keystore: Keystore,
    pub(crate) identify_conf: IdentifyConfiguration,
    pub(crate) to_task: Sender<IpfsEvent>,
    pub(crate) record_key_validator: HashMap<String, Arc<dyn Fn(&str) -> Result<Key, Error> + Sync + Send>>,
    pub(crate) _guard: Arc<DropGuard>,
}

Server, Client, or Auto mode The facade for the Ipfs node.

The facade has most of the functionality either directly as a method or the functionality can be implemented using the provided methods. For more information, see examples or the HTTP endpoint implementations in ipfs-http.

The facade is created through [UninitializedIpfs] which is configured with [IpfsOptions].

Fields

span: Span

repo: Repo

key: Keypair

keystore: Keystore

identify_conf: IdentifyConfiguration

to_task: Sender<IpfsEvent>

record_key_validator: HashMap<String, Arc<dyn Fn(&str) -> Result<Key, Error> + Sync + Send>>

_guard: Arc<DropGuard>

Implementations

impl Ipfs

pub fn dag(&self) -> IpldDag

Return an [IpldDag] for DAG operations

pub fn repo(&self) -> &Repo

Return an [Repo] to access the internal repo of the node

pub fn unixfs(&self) -> IpfsUnixfs

Returns an [IpfsUnixfs] for files operations

pub fn ipns(&self) -> Ipns

Returns a [Ipns] for ipns operations

pub async fn put_block( &self, block: Block<DefaultParams>, ) -> Result<Cid<64>, Error>

Puts a block into the ipfs repo.

pub async fn get_block( &self, cid: &Cid<64>, ) -> Result<Block<DefaultParams>, Error>

Retrieves a block from the local blockstore, or starts fetching from the network or join an already started fetch.

pub async fn remove_block( &self, cid: Cid<64>, recursive: bool, ) -> Result<Vec<Cid<64>>, Error>

Remove block from the ipfs repo. A pinned block cannot be removed.

pub async fn gc(&self) -> Result<Vec<Cid<64>>, Error>

Cleans up of all unpinned blocks Note: This will prevent writing operations in [Repo] until it finish clearing unpinned blocks.

pub fn insert_pin(&self, cid: &Cid<64>) -> RepoInsertPin

Pins a given Cid recursively or directly (non-recursively).

Pins on a block are additive in sense that a previously directly (non-recursively) pinned can be made recursive, but removing the recursive pin on the block removes also the direct pin as well.

Pinning a Cid recursively (for supported dag-protobuf and dag-cbor) will walk its references and pin the references indirectly. When a Cid is pinned indirectly it will keep its previous direct or recursive pin and be indirect in addition.

Recursively pinned Cids cannot be re-pinned non-recursively but non-recursively pinned Cids can be “upgraded to” being recursively pinned.

Crash unsafety

If a recursive insert_pin operation is interrupted because of a crash or the crash prevents from synchronizing the data store to disk, this will leave the system in an inconsistent state. The remedy is to re-pin recursive pins.

pub fn remove_pin(&self, cid: &Cid<64>) -> RepoRemovePin

Unpins a given Cid recursively or only directly.

Recursively unpinning a previously only directly pinned Cid will remove the direct pin.

Unpinning an indirectly pinned Cid is not possible other than through its recursively pinned tree roots.

pub async fn is_pinned(&self, cid: &Cid<64>) -> Result<bool, Error>

Checks whether a given block is pinned.

Returns true if the block is pinned, false if not. See Crash unsafety notes for the false response.

Crash unsafety

Cannot currently detect partially written recursive pins. Those can happen if Ipfs::insert_pin is interrupted by a crash for example.

Works correctly only under no-crash situations. Workaround for hitting a crash is to re-pin any existing recursive pins.

pub async fn list_pins( &self, filter: Option<PinMode>, ) -> Pin<Box<dyn Stream<Item = Result<(Cid<64>, PinMode), Error>> + Send>>

Lists all pins, or the specific kind thereof.

Crash unsafety

Does not currently recover from partial recursive pin insertions.

pub async fn query_pins( &self, cids: Vec<Cid<64>>, requirement: Option<PinMode>, ) -> Result<Vec<(Cid<64>, PinKind<Cid<64>>)>, Error>

Read specific pins. When requirement is Some, all pins are required to be of the given [PinMode].

Crash unsafety

Does not currently recover from partial recursive pin insertions.

pub fn put_dag(&self, ipld: Ipld) -> DagPut

Puts an ipld node into the ipfs repo using dag-cbor codec and Sha2_256 hash.

Returns Cid version 1 for the document

pub fn get_dag<I>(&self, path: I) -> DagGet

where I: Into<IpfsPath>,

Gets an ipld node from the ipfs, fetching the block if necessary.

See [IpldDag::get] for more information.

pub fn cat_unixfs(&self, starting_point: impl Into<StartingPoint>) -> UnixfsCat

Creates a stream which will yield the bytes of an UnixFS file from the root Cid, with the optional file byte range. If the range is specified and is outside of the file, the stream will end without producing any bytes.

pub fn add_unixfs(&self, opt: impl Into<AddOpt>) -> UnixfsAdd

Add a file through a stream of data to the blockstore

pub fn get_unixfs<P>(&self, path: IpfsPath, dest: P) -> UnixfsGet

where P: AsRef<Path>,

Retreive a file and saving it to a path.

pub fn ls_unixfs(&self, path: IpfsPath) -> UnixfsLs

List directory contents

pub async fn resolve_ipns( &self, path: &IpfsPath, recursive: bool, ) -> Result<IpfsPath, Error>

Resolves a ipns path to an ipld path; currently only supports dht and dnslink resolution.

pub async fn publish_ipns(&self, path: &IpfsPath) -> Result<IpfsPath, Error>

Publish ipns record to DHT

pub async fn connect(&self, target: impl Into<DialOpts>) -> Result<(), Error>

Connects to the peer

pub async fn addrs(&self) -> Result<Vec<(PeerId, Vec<Multiaddr>)>, Error>

Returns known peer addresses

pub async fn is_connected(&self, peer_id: PeerId) -> Result<bool, Error>

Checks whether there is an established connection to a peer.

pub async fn connected(&self) -> Result<Vec<PeerId>, Error>

Returns the connected peers

pub async fn disconnect(&self, target: PeerId) -> Result<(), Error>

Disconnects a given peer.

pub async fn ban_peer(&self, target: PeerId) -> Result<(), Error>

Bans a peer.

pub async fn unban_peer(&self, target: PeerId) -> Result<(), Error>

Unbans a peer.

pub async fn identity(&self, peer_id: Option<PeerId>) -> Result<PeerInfo, Error>

Returns the peer identity information. If no peer id is supplied the local node identity is used.

pub async fn pubsub_subscribe( &self, topic: impl Into<String>, ) -> Result<SubscriptionStream, Error>

Subscribes to a given topic. Can be done at most once without unsubscribing in the between. The subscription can be unsubscribed by dropping the stream or calling Ipfs::pubsub_unsubscribe.

pub async fn pubsub_events( &self, topic: impl Into<String>, ) -> Result<Pin<Box<dyn Stream<Item = PubsubEvent> + Send>>, Error>

Stream that returns [PubsubEvent] for a given topic

pub async fn pubsub_publish( &self, topic: impl Into<String>, data: impl Into<Bytes>, ) -> Result<MessageId, Error>

Publishes to the topic which may have been subscribed to earlier

pub async fn pubsub_unsubscribe( &self, topic: impl Into<String>, ) -> Result<bool, Error>

Forcibly unsubscribes a previously made SubscriptionStream, which could also be unsubscribed by dropping the stream.

Returns true if unsubscription was successful

pub async fn pubsub_peers( &self, topic: impl Into<Option<String>>, ) -> Result<Vec<PeerId>, Error>

Returns all known pubsub peers with the optional topic filter

pub async fn pubsub_subscribed(&self) -> Result<Vec<String>, Error>

Returns all currently subscribed topics

pub async fn bitswap_wantlist( &self, peer: impl Into<Option<PeerId>>, ) -> Result<Vec<Cid<64>>, Error>

Returns the known wantlist for the local node when the peer is None or the wantlist of the given peer

pub async fn refs_local(&self) -> Vec<Cid<64>>

Returns a list of local blocks

pub async fn listening_addresses(&self) -> Result<Vec<Multiaddr>, Error>

Returns local listening addresses

pub async fn external_addresses(&self) -> Result<Vec<Multiaddr>, Error>

Returns external addresses

pub async fn add_listening_address( &self, addr: Multiaddr, ) -> Result<Multiaddr, Error>

Add a given multiaddr as a listening address. Will fail if the address is unsupported, or if it is already being listened on. Currently will invoke Swarm::listen_on internally, returning the first Multiaddr that is being listened on.

pub async fn remove_listening_address( &self, addr: Multiaddr, ) -> Result<(), Error>

Stop listening on a previously added listening address. Fails if the address is not being listened to.

The removal of all listening addresses added through unspecified addresses is not supported.

pub async fn add_external_address(&self, addr: Multiaddr) -> Result<(), Error>

Add a given multiaddr as a external address to indenticate how our node can be reached. Note: We will not perform checks

pub async fn remove_external_address( &self, addr: Multiaddr, ) -> Result<(), Error>

Removes a previously added external address.

pub async fn find_peer(&self, peer_id: PeerId) -> Result<Vec<Multiaddr>, Error>

Obtain the addresses associated with the given PeerId; they are first searched for locally and the DHT is used as a fallback: a Kademlia::get_closest_peers(peer_id) query is run and when it’s finished, the newly added DHT records are checked for the existence of the desired peer_id and if it’s there, the list of its known addresses is returned.

pub async fn get_providers( &self, cid: Cid<64>, ) -> Result<Pin<Box<dyn Stream<Item = PeerId> + Send>>, Error>

Performs a DHT lookup for providers of a value to the given key.

Returns a list of peers found providing the Cid.

pub async fn provide(&self, cid: Cid<64>) -> Result<(), Error>

Establishes the node as a provider of a block with the given Cid: it publishes a provider record with the given key (Cid) and the node’s PeerId to the peers closest to the key. The publication of provider records is periodically repeated as per the interval specified in libp2p’s KademliaConfig.

pub fn fetch(&self, cid: &Cid<64>) -> RepoFetch

Fetches the block, and, if set, recursively walk the graph loading all the blocks to the blockstore.

pub async fn get_closest_peers( &self, peer_id: PeerId, ) -> Result<Vec<PeerId>, Error>

Returns a list of peers closest to the given PeerId, as suggested by the DHT. The node must have at least one known peer in its routing table in order for the query to return any values.

pub async fn dht_mode(&self, mode: DhtMode) -> Result<(), Error>

Change the DHT mode

pub async fn dht_get<T>( &self, key: T, ) -> Result<Pin<Box<dyn Stream<Item = Record> + Send>>, Error>

where T: AsRef<[u8]>,

Attempts to look a key up in the DHT and returns the values found in the records containing that key.

pub async fn dht_put( &self, key: impl AsRef<[u8]>, value: impl Into<Vec<u8>>, quorum: Quorum, ) -> Result<(), Error>

Stores the given key + value record locally and replicates it in the DHT. It doesn’t expire locally and is periodically replicated in the DHT, as per the KademliaConfig setup.

pub async fn add_relay( &self, peer_id: PeerId, addr: Multiaddr, ) -> Result<(), Error>

Add relay address

pub async fn remove_relay( &self, peer_id: PeerId, addr: Multiaddr, ) -> Result<(), Error>

Remove relay address

pub async fn list_relays( &self, active: bool, ) -> Result<Vec<(PeerId, Vec<Multiaddr>)>, Error>

List all relays. if active is true, it will list all active relays

pub async fn enable_autorelay(&self) -> Result<(), Error>

pub async fn disable_autorelay(&self) -> Result<(), Error>

pub async fn enable_relay( &self, peer_id: impl Into<Option<PeerId>>, ) -> Result<(), Error>

Enable use of a relay. If peer_id is None, it will select a relay at random to use, if one have been added

pub async fn disable_relay(&self, peer_id: PeerId) -> Result<(), Error>

Disable the use of a selected relay.

pub async fn rendezvous_register_namespace( &self, namespace: impl Into<String>, ttl: impl Into<Option<u64>>, peer_id: PeerId, ) -> Result<(), Error>

pub async fn rendezvous_unregister_namespace( &self, namespace: impl Into<String>, peer_id: PeerId, ) -> Result<(), Error>

pub async fn rendezvous_namespace_discovery( &self, namespace: impl Into<String>, ttl: impl Into<Option<u64>>, peer_id: PeerId, ) -> Result<HashMap<PeerId, Vec<Multiaddr>>, Error>

pub fn refs<'a, Iter>( &'a self, iplds: Iter, max_depth: Option<u64>, unique: bool, ) -> impl Stream<Item = Result<Edge, Error>> + Send + 'a

where Iter: IntoIterator<Item = (Cid<64>, Ipld)> + Send + 'a,

Walk the given Iplds’ links up to max_depth (or indefinitely for None). Will return any duplicate trees unless unique is true.

More information and a 'static lifetime version available at [refs::iplds_refs].

pub async fn get_bootstraps(&self) -> Result<Vec<Multiaddr>, Error>

Obtain the list of addresses of bootstrapper nodes that are currently used.

pub async fn add_bootstrap(&self, addr: Multiaddr) -> Result<Multiaddr, Error>

Extend the list of used bootstrapper nodes with an additional address. Return value cannot be used to determine if the addr was a new bootstrapper, subject to change.

pub async fn remove_bootstrap( &self, addr: Multiaddr, ) -> Result<Multiaddr, Error>

Remove an address from the currently used list of bootstrapper nodes. Return value cannot be used to determine if the addr was an actual bootstrapper, subject to change.

pub async fn clear_bootstrap(&self) -> Result<Vec<Multiaddr>, Error>

Clear the currently used list of bootstrapper nodes, returning the removed addresses.

pub async fn default_bootstrap(&self) -> Result<Vec<Multiaddr>, Error>

Restore the originally configured bootstrapper node list by adding them to the list of the currently used bootstrapper node address list; returns the restored addresses.

pub async fn bootstrap(&self) -> Result<(), Error>

Bootstraps the local node to join the DHT: it looks up the node’s own ID in the DHT and introduces it to the other nodes in it; at least one other node must be known in order for the process to succeed. Subsequently, additional queries are ran with random keys so that the buckets farther from the closest neighbor also get refreshed.

pub async fn add_peer( &self, peer_id: PeerId, addr: Multiaddr, ) -> Result<(), Error>

Add address of a peer to the address book

pub async fn remove_peer(&self, peer_id: PeerId) -> Result<bool, Error>

Remove peer from the address book

pub async fn remove_peer_address( &self, peer_id: PeerId, addr: Multiaddr, ) -> Result<bool, Error>

Remove peer address from the address book

pub async fn get_bitswap_peers(&self) -> Result<Vec<PeerId>, Error>

Returns the Bitswap peers for the a Node.

pub fn keypair(&self) -> &Keypair

Returns the keypair to the node

pub fn keystore(&self) -> &Keystore

Returns the keystore

pub async fn exit_daemon(self)

Exit daemon.

Trait Implementations

impl Clone for Ipfs

fn clone(&self) -> Ipfs

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Ipfs

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl From<Ipfs> for HermesIpfs

fn from(node: Ipfs) -> Self

Converts to this type from the input type.