Struct sn_api::Safe

pub struct Safe {
    pub xorurl_base: XorUrlBase,
    pub dry_run_mode: bool,
    /* private fields */
}

Fields

xorurl_base: XorUrlBase

dry_run_mode: bool

Implementations

impl Safe

pub async fn files_container_create(&self) -> Result<XorUrl>

Create an empty FilesContainer.

Example

    let mut safe = Safe::connected(None, None, None, None).await.unwrap();
    let xorurl = safe.files_container_create().await.unwrap();
    assert!(xorurl.contains("safe://"))

pub async fn files_container_create_from<P: AsRef<Path>>( &self, location: P, dst: Option<&Path>, recursive: bool, follow_links: bool ) -> Result<(XorUrl, ProcessedFiles, FilesMap)>

Create a FilesContainer containing files uploaded from a local folder.

Example

    let mut safe = Safe::connected(None, None, None, None).await.unwrap();
    let (xorurl, _processed_files, _files_map) = safe.files_container_create_from("./testdata", None, true, true).await.unwrap();
    assert!(xorurl.contains("safe://"))

pub async fn files_container_get( &self, url: &str ) -> Result<Option<(VersionHash, FilesMap)>>

Fetch an existing FilesContainer.

Example

    let (xorurl, _processed_files, _files_map) = safe.files_container_create_from("./testdata", None, true, true).await.unwrap();
    let (version, files_map) = safe.files_container_get(&xorurl).await.unwrap().unwrap();
    println!("FilesContainer fetched is at version: {}", version);
    println!("FilesMap of fetched version is: {:?}", files_map);

pub async fn files_container_sync<P: AsRef<Path>>( &self, location: P, url: &str, recursive: bool, follow_links: bool, delete: bool, update_nrs: bool ) -> Result<(Option<(VersionHash, FilesMap)>, ProcessedFiles)>

Sync up local folder with the content on a FilesContainer.

Example

    let (xorurl, _processed_files, _files_map) = safe.files_container_create_from("./testdata", None, true, false).await.unwrap();
    let (optional_version_map, new_processed_files) = safe.files_container_sync("./testdata", &xorurl, true, true, false, false).await.unwrap();
    if let Some((version, new_files_map)) = optional_version_map {
        println!("FilesContainer is now at version: {}", version);
        println!("The local files that were synced up are: {:?}", new_processed_files);
        println!("The FilesMap of the updated FilesContainer now is: {:?}", new_files_map);
    }

pub async fn files_container_add( &self, source_file: &str, url: &str, force: bool, update_nrs: bool, follow_links: bool ) -> Result<(Option<(VersionHash, FilesMap)>, ProcessedFiles)>

Add a file, either a local path or an already uploaded file, on an existing FilesContainer.

Example

    let (xorurl, _processed_files, _files_map) = safe.files_container_create_from("./testdata", None, true, true).await.unwrap();
    let new_file_name = format!("{}/new_name_test.md", xorurl);
    let (optional_version_map, new_processed_files) = safe.files_container_add("./testdata/test.md", &new_file_name, false, false, true).await.unwrap();
    if let Some((version, new_files_map)) = optional_version_map {
        println!("FilesContainer is now at version: {}", version);
        println!("The local files that were synced up are: {:?}", new_processed_files);
        println!("The FilesMap of the updated FilesContainer now is: {:?}", new_files_map);
    }

pub async fn files_container_add_from_raw( &self, data: Bytes, url: &str, force: bool, update_nrs: bool ) -> Result<(Option<(VersionHash, FilesMap)>, ProcessedFiles)>

Add a file, from raw bytes, on an existing FilesContainer.

Example

    let (xorurl, _processed_files, _files_map) = safe.files_container_create_from("./testdata", None, true, true).await.unwrap();
    let new_file_name = format!("{}/new_name_test.md", xorurl);
    let (optional_version_map, new_processed_files) = safe.files_container_add_from_raw(Bytes::from("0123456789"), &new_file_name, false, false).await.unwrap();
    if let Some((version, new_files_map)) = optional_version_map {
        println!("FilesContainer is now at version: {}", version);
        println!("The local files that were synced up are: {:?}", new_processed_files);
        println!("The FilesMap of the updated FilesContainer now is: {:?}", new_files_map);
    }

pub async fn files_container_remove_path( &self, url: &str, recursive: bool, update_nrs: bool ) -> Result<(VersionHash, ProcessedFiles, FilesMap)>

Remove a file from an existing FilesContainer.

Example

    let (xorurl, processed_files, files_map) = safe.files_container_create_from("./testdata/", None, true, true).await.unwrap();
    let remote_file_path = format!("{}/test.md", xorurl);
    let (version, new_processed_files, new_files_map) = safe.files_container_remove_path(&remote_file_path, false, false).await.unwrap();
    println!("FilesContainer is now at version: {}", version);
    println!("The files that were removed: {:?}", new_processed_files);
    println!("The FilesMap of the updated FilesContainer now is: {:?}", new_files_map);

pub async fn store_bytes( &self, bytes: Bytes, media_type: Option<&str> ) -> Result<XorUrl>

Store a file

Store files onto the network. The data will be saved as one or more chunks, depending on the size of the data. If it’s less than 3072 bytes, it’ll be stored in a single chunk, otherwise, it’ll be stored in multiple chunks.

Example

    let data = Bytes::from("Something super good");
    let xorurl = safe.store_bytes(data.clone(), Some("text/plain")).await.unwrap();
    let received_data = safe.files_get(&xorurl, None).await.unwrap();
    assert_eq!(received_data, data);

pub async fn files_get(&self, url: &str, range: Range) -> Result<Bytes>

Get a file

Get file from the network.

Example

    let data = Bytes::from("Something super good");
    let xorurl = safe.store_bytes(data.clone(), None).await.unwrap();
    let received_data = safe.files_get(&xorurl, None).await.unwrap();
    assert_eq!(received_data, data);

impl Safe

pub async fn validate_sk_for_url( &self, secret_key: &SecretKey, url: &str ) -> Result<String>

Check the XOR/NRS-URL corresponds to the public key derived from the provided client id.

pub fn new_keypair_with_pk_url(&self) -> Result<(Keypair, SafeUrl)>

Generate a new random BLS keypair along with a URL for the public key.

pub fn serialize_bls_key( secret_key: &BlsSecretKey, path: impl AsRef<Path> ) -> Result<()>

Serializes a SecretKey to hex in a file at a given path.

If the path already exists it will be overwritten.

pub fn deserialize_bls_key(path: impl AsRef<Path>) -> Result<BlsSecretKey>

Deserializes a Keypair from file at a given path.

A utility to help callers working with keypairs avoid using serde or bincode directly.

impl Safe

pub async fn multimap_create( &self, name: Option<XorName>, type_tag: u64 ) -> Result<XorUrl>

Create a Multimap on the network

pub async fn multimap_get_by_key( &self, url: &str, key: &[u8] ) -> Result<Multimap>

Return the value of a Multimap on the network corresponding to the key provided

pub async fn multimap_get_by_hash( &self, url: &str, hash: EntryHash ) -> Result<MultimapKeyValue>

Return the value of a Multimap on the network corresponding to the hash provided

pub async fn multimap_insert( &self, multimap_url: &str, entry: MultimapKeyValue, replace: BTreeSet<EntryHash> ) -> Result<EntryHash>

Insert a key-value pair into a Multimap on the network

pub async fn multimap_remove( &self, url: &str, to_remove: BTreeSet<EntryHash> ) -> Result<EntryHash>

Remove entries from a Multimap on the network This tombstones the removed entries, effectively hiding them if they where the latest Note that they are still stored on the network as history is kept, and you can still access them with their EntryHash

impl Safe

pub async fn nrs_create(&self, top_name: &str) -> Result<SafeUrl>

Creates a nrs_map_container for a chosen top name

safe://<subName>.<topName>/path/to/whatever?var=value
       |-----------------|
           Public Name

Registers the given NRS top name on the network. Returns the NRS SafeUrl: safe://{top_name} Note that this NRS SafeUrl is not linked to anything yet. You just registered the topname here. You can now associate public_names (with that topname) to links using nrs_associateornrs_add`

pub async fn nrs_associate( &self, public_name: &str, link: &SafeUrl ) -> Result<SafeUrl>

Associates a public name to a link

The top name of the input public name needs to be registered first with nrs_create

safe://<subName>.<topName>/path/to/whatever?var=value
       |-----------------|
           Public Name

Associates the given public_name to the link. Errors out if the topname is not registered. Returns the versioned NRS SafeUrl (containing a VersionHash) now pointing to the provided link: safe://{public_name}?v={version_hash}

pub async fn nrs_add( &self, public_name: &str, link: &SafeUrl ) -> Result<(SafeUrl, bool)>

Associates any public name to a link

Associates the given public_name to the link registering the topname on the way if needed. Returns the versioned NRS SafeUrl (containing a VersionHash) now pointing to the provided link: safe://{public_name}?v={version_hash} Also returns a bool to indicate whether it registered the topname in the process or not.

pub async fn nrs_remove(&self, public_name: &str) -> Result<SafeUrl>

Removes a public name

The top name of the input public name needs to be registered first with nrs_create

safe://<subName>.<topName>/path/to/whatever?var=value
       |-----------------|
           Public Name

Removes the given public_name from the NrsMap registered for the public name’s top name on the network. Returns a versioned NRS SafeUrl (containing a VersionHash) pointing to the latest version (including the deletion) for the provided public name. safe://{public_name}?v={version_hash}

pub async fn nrs_get( &self, public_name: &str, version: Option<VersionHash> ) -> Result<(Option<SafeUrl>, NrsMap)>

Gets a public name’s associated link

If no version is specified, returns the latest. The top name of the input public name needs to be registered first with nrs_create

safe://<subName>.<topName>/path/to/whatever?var=value
       |-----------------|
           Public Name

Finds the SafeUrl associated with the given public name on the network. If multiple entries are found for the same public name, there’s a conflict. If there are conflicts for subnames other than the one requested, get proceeds as usual, but the NrsMap returned will ignore those conflicts. Otherwise, it returns an error. Returns the associated SafeUrl for the given public name for that version along with an NrsMap

pub async fn nrs_get_subnames_map( &self, public_name: &str, version: Option<VersionHash> ) -> Result<NrsMap>

Get the mapping of all subNames and their associated SafeUrl for the Nrs Map Container at the given public name

impl Safe

pub async fn register_create( &self, name: Option<XorName>, tag: u64, content_type: ContentType ) -> Result<XorUrl>

Create a Register on the network

pub async fn register_read( &self, url: &str ) -> Result<BTreeSet<(EntryHash, Entry)>>

Read value from a Register on the network

pub async fn register_read_entry( &self, url: &str, hash: EntryHash ) -> Result<Entry>

Read value from a Register on the network by its hash

pub async fn register_write( &self, url: &str, entry: Entry, parents: BTreeSet<EntryHash> ) -> Result<EntryHash>

Write value to a Register on the network

impl Safe

pub async fn parse_and_resolve_url(&self, url: &str) -> Result<SafeUrl>

Parses a string URL “safe://url” and returns a safe URL Resolves until it reaches the final URL

pub async fn fetch(&self, url: &str, range: Range) -> Result<SafeData>

Retrieve data from a safe:// URL

Examples

Fetch FilesContainer relative path file

    let (xorurl, _, _) = safe.files_container_create_from("./testdata/", None, true, false).await.unwrap();

    let safe_data = safe.fetch( &format!( "{}/test.md", &xorurl.replace("?v=0", "") ), None ).await.unwrap();
    let data_string = match safe_data {
        SafeData::PublicFile { data, .. } => {
            match String::from_utf8(data.to_vec()) {
                Ok(string) => string,
                Err(e) => panic!("Invalid UTF-8 sequence: {}", e),
            }
        }
        other => panic!(
            "Content type '{:?}' should not have been found. This should be immutable data.",
            other
        )
    };

    assert!(data_string.starts_with("hello tests!"));

pub async fn inspect(&self, url: &str) -> Result<Vec<SafeData>>

Inspect a safe:// URL and retrieve metadata information but the actual target content

As opposed to ‘fetch’ function, the actual target content won’t be fetched, and only

the URL will be inspected resolving it as necessary to find the target location.

This is helpful if you are interested in knowing about the target content,

and/or each of the SafeUrl resolution steps taken to the target content, rather than

trying to revieve the actual content.

Examples

Inspect FilesContainer relative path file

    let (container_xorurl, _, _) = safe.files_container_create_from("./testdata/", None, true, false).await.unwrap();

    let inspected_content = safe.inspect( &format!( "{}/test.md", &container_xorurl.replace("?v=0", "") ) ).await.unwrap();
    match &inspected_content[0] {
        SafeData::FilesContainer { xorurl, .. } => {
            assert_eq!(*xorurl, container_xorurl);
        }
        other => panic!(
            "Content type '{:?}' should not have been found. This should be a Files Container.",
            other
        )
    };
    match &inspected_content[1] {
        SafeData::PublicFile { data, media_type, .. } => {
            assert_eq!(*media_type, Some("text/markdown".to_string()));
            assert!(data.is_empty());
        }
        other => panic!(
            "Content type '{:?}' should not have been found. This should be an Immutable Data.",
            other
        )
    };

pub async fn check_replicas( &self, url: &str, replicas: &[usize] ) -> Result<Vec<QueriedDataReplicas>>

Resolve the provided Url, and try to query each of the data replicas matching the given indexes, returning the list of query results obtained from each replica. Currently only Urls resolving to a File are supported.

impl Safe

pub async fn wallet_create(&self) -> Result<XorUrl>

Create an empty wallet and return its XOR-URL.

A wallet is stored on a private register.

pub async fn wallet_deposit( &self, wallet_url: &str, spendable_name: Option<&str>, dbc: &Dbc, secret_key: Option<SecretKey> ) -> Result<(String, Token)>

Deposit a DBC in a wallet to make it a spendable balance.

A name can optionally be specified for the deposit. If it isn’t, part of the hash of the DBC content will be used. Note this won’t perform a verification on the network to check if the the DBC has been already spent, the user can call to is_dbc_spent API for that purpose beforehand.

Returns the name that was set, along with the deposited amount.

pub async fn is_dbc_spent(&self, public_key: PublicKey) -> Result<bool>

Verify if the provided DBC’s public_key has been already spent on the network.

pub async fn wallet_get(&self, wallet_url: &str) -> Result<WalletSpendableDbcs>

Fetch a wallet from a Url performing all type of URL resolution required. Return the set of spendable DBCs found in the wallet.

pub async fn wallet_balance(&self, wallet_url: &str) -> Result<Token>

Check the total balance of a wallet found at a given XOR-URL

pub async fn wallet_reissue( &self, wallet_url: &str, amount: &str, owner_public_key: Option<PublicKey>, reason: DbcReason ) -> Result<Dbc>

Reissue a DBC from a wallet and return the output DBC.

If you pass None for the owner_public_key argument, the output DBC will be a bearer. If the public key is specified, the output DBC will be owned by the person in possession of the secret key corresponding to the public key.

If there is change from the transaction, the change DBC will be deposited in the source wallet.

Spent DBCs are marked as removed from the source wallet, but since all entries are kept in the history, they can still be retrieved if desired by the user.

pub async fn wallet_reissue_many( &self, wallet_url: &str, outputs: Vec<(String, Option<PublicKey>)>, reason: DbcReason ) -> Result<Vec<Dbc>>

Reissue several DBCs from a wallet.

This works exactly the same as wallet_reissue API with the only difference that this function allows to reissue from a single wallet several output DBCs instead of a single one. If there is change from the transaction, the change DBC will be deposited in the source wallet.

impl Safe

pub async fn auth_app( app_id: &str, app_name: &str, app_vendor: &str, endpoint: Option<&str>, authd_cert_path: impl AsRef<Path> ) -> Result<Keypair>

Generate an authorisation request string and send it to a SAFE Authenticator. It returns the credentials necessary to connect to the network, encoded in a single string.

impl Safe

pub fn dry_runner(xorurl_base: Option<XorUrlBase>) -> Self

Create a Safe instance without connecting to the SAFE Network

pub async fn connected( keypair: Option<Keypair>, xorurl_base: Option<XorUrlBase>, timeout: Option<Duration>, dbc_owner: Option<Owner> ) -> Result<Self>

Create a Safe instance connected to the SAFE Network

pub async fn connect( &mut self, keypair: Option<Keypair>, timeout: Option<Duration>, dbc_owner: Option<Owner> ) -> Result<()>

Connect to the SAFE Network

pub fn is_connected(&self) -> bool

Returns true if we already have a connection with the network

pub async fn section_tree(&self) -> Result<SectionTree>

SectionTree used to bootstrap on the network.

This is updated by as Anti-Entropy/update messages are received from the network. Any user of this API is responsible for caching it so it can use it for any new Safe instance, preventing it from learning all this information from the network all over again.

Trait Implementations

impl Clone for Safe

fn clone(&self) -> Safe

Returns a copy of the value.

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

Performs copy-assignment from source.