Struct rust_ipfs::Ipfs

pub struct Ipfs<Types: IpfsTypes> { /* private fields */ }

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.

Implementations

impl<Types: IpfsTypes> Ipfs<Types>

pub fn dag(&self) -> IpldDag<Types>

Return an IpldDag for DAG operations

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

Puts a block into the ipfs repo.

Forget safety

Forgetting the returned future will not result in memory unsafety, but it can deadlock other tasks.

pub async fn get_block(&self, cid: &Cid) -> Result<Block, 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) -> Result<Cid, Error>

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

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

Cleans up of all unpinned blocks Note: This is extremely basic and should not be relied on completely until there is additional or extended implementation for a gc

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

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 async fn remove_pin(&self, cid: &Cid, recursive: bool) -> Result<(), Error>

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) -> 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(cid, true) 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> ) -> BoxStream<'static, Result<(Cid, PinMode), Error>>

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>, requirement: Option<PinMode> ) -> Result<Vec<(Cid, PinKind<Cid>)>, 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 async fn put_dag(&self, ipld: Ipld) -> Result<Cid, Error>

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

Returns Cid version 1 for the document

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

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

See IpldDag::get for more information.

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

Get an ipld path from the datastore. Note: This will be replaced in the future and shouldnt be depended on completely

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

Put an ipld path into the datastore. Note: This will be replaced in the future and shouldnt be depended on completely

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

Remove an ipld path from the datastore. Note: This will be replaced in the future and shouldnt be depended on completely

pub async fn cat_unixfs( &self, starting_point: impl Into<StartingPoint>, range: Option<Range<u64>> ) -> Result<impl Stream<Item = Result<Vec<u8>, TraversalFailed>> + Send + '_, TraversalFailed>

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.

To create an owned version of the stream, please use ipfs::unixfs::cat directly.

pub async fn add_file_unixfs<P: AsRef<Path>>( &self, path: P ) -> Result<BoxStream<'_, UnixfsStatus>, Error>

Add a file from a path to the blockstore

pub async fn add_unixfs( &self, stream: BoxStream<'static, Vec<u8>> ) -> Result<BoxStream<'_, UnixfsStatus>, Error>

Add a file through a stream of data to the blockstore

pub async fn get_unixfs<P: AsRef<Path>>( &self, path: IpfsPath, dest: P ) -> Result<BoxStream<'_, UnixfsStatus>, Error>

Retreive a file and saving it to a path.

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

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

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

Connects to the peer at the given Multiaddress.

Accepts only multiaddresses with the PeerId to authenticate the connection.

Returns a future which will complete when the connection has been successfully made or failed for whatever reason. It is possible for this method to return an error, while ending up being connected to the peer by the means of another connection.

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

Dials a peer using [Swarm::dial].

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

Returns known peer addresses

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

Returns local listening addresses

pub async fn peers(&self) -> Result<Vec<Connection>, Error>

Returns the connected peers

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 protocols(&self) -> Result<Vec<String>, Error>

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: 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_publish( &self, topic: String, data: Vec<u8> ) -> Result<MessageId, Error>

Publishes to the topic which may have been subscribed to earlier

pub async fn pubsub_unsubscribe(&self, topic: &str) -> 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: 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: Option<PeerId> ) -> Result<Vec<(Cid, Priority)>, 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) -> Result<Vec<Cid>, Error>

Returns a list of local blocks

This implementation is subject to change into a stream, which might only include the pinned blocks.

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

Returns the accumulated bitswap stats

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, keep the ListenerId for later remove_listening_address use in a HashMap.

The returned future will resolve on the first bound listening address when this is called with /ip4/0.0.0.0/... or anything similar which will bound through multiple concrete listening addresses.

Trying to add an unspecified listening address while any other listening address adding is in progress will result in error.

Returns the bound multiaddress, which in the case of original containing an ephemeral port has now been changed.

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 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 ) -> Result<BoxStream<'static, PeerId>, 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) -> 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 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_get<T: Into<Key>>(&self, key: T) -> Result<RecordStream, Error>

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<T: Into<Key>>( &self, key: T, value: 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, _: Multiaddr) -> Result<(), Error>

pub async fn remove_relay(&self, _: Vec<Multiaddr>) -> Result<(), Error>

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

pub async fn relay_status(&self, _: Option<PeerId>) -> Result<(), Error>

pub async fn set_relay(&self, _: Multiaddr) -> Result<(), Error>

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

pub fn refs<'a, Iter>( &'a self, iplds: Iter, max_depth: Option<u64>, unique: bool ) -> impl Stream<Item = Result<Edge, Error>> + Send + 'awhere Iter: IntoIterator<Item = (Cid, 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: MultiaddrWithPeerId ) -> 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: MultiaddrWithPeerId ) -> 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<JoinHandle<Result<KadResult, Error>>, 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: Option<Multiaddr> ) -> Result<(), Error>

Add a known listen address of a peer participating in the DHT to the routing table. This is mandatory in order for the peer to be discoverable by other members of the DHT.

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

Returns the Bitswap peers for the a Node.

pub async fn exit_daemon(self)

Exit daemon.

Trait Implementations

impl<Types: IpfsTypes> Clone for Ipfs<Types>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<Types: Debug + IpfsTypes> Debug for Ipfs<Types>

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

Formats the value using the given formatter.