Struct golgi::sbot::Sbot

pub struct Sbot {
    pub id: String,
    /* private fields */
}

Holds the Scuttlebutt identity, keys and configuration parameters for connecting to a local sbot and implements all Golgi API methods.

Fields

id: String

The ID (public key value) of the account associated with the local sbot instance.

Implementations

impl Sbot

pub async fn get_about_message_stream(
    &mut self,
    ssb_id: &str
) -> Result<impl Stream<Item = Result<SsbMessageValue, GolgiError>>, GolgiError>

Get all the about type messages for a peer in order of recency (ie. most recent messages first).

Example

use async_std::stream::{Stream, StreamExt};
use golgi::{Sbot, GolgiError};

async fn about_message_stream() -> Result<(), GolgiError> {
    let mut sbot_client = Sbot::init(None, None).await?;

    let ssb_id = "@zqshk7o2Rpd/OaZ/MxH6xXONgonP1jH+edK9+GZb/NY=.ed25519";

    let about_message_stream = sbot_client.get_about_message_stream(ssb_id).await?;

    // Make the stream into an iterator.
    futures::pin_mut!(about_message_stream);

    about_message_stream.for_each(|msg| {
        match msg {
            Ok(val) => println!("msg value: {:?}", val),
            Err(e) => eprintln!("error: {}", e),
        }
    }).await;

    Ok(())
}

pub async fn get_latest_about_message(
    &mut self,
    ssb_id: &str,
    key: &str
) -> Result<Option<String>, GolgiError>

Get the value of the latest about type message, containing the given key, for a peer.

Example

use golgi::{Sbot, GolgiError};

async fn name_info() -> Result<(), GolgiError> {
    let mut sbot_client = Sbot::init(None, None).await?;

    let ssb_id = "@zqshk7o2Rpd/OaZ/MxH6xXONgonP1jH+edK9+GZb/NY=.ed25519";
    let key = "name";

    let name_info = sbot_client.get_latest_about_message(ssb_id, key).await?;

    match name_info {
        Some(name) => println!("peer {} is named {}", ssb_id, name),
        None => println!("no name found for peer {}", ssb_id)
    }

    Ok(())
}

pub async fn get_profile_info(
    &mut self,
    ssb_id: &str
) -> Result<HashMap<String, String>, GolgiError>

Get the latest name, description and image values for a peer, as defined in their about type messages.

Example

use golgi::{Sbot, GolgiError};

async fn profile_info() -> Result<(), GolgiError> {
    let mut sbot_client = Sbot::init(None, None).await?;

    let ssb_id = "@zqshk7o2Rpd/OaZ/MxH6xXONgonP1jH+edK9+GZb/NY=.ed25519";

    let profile_info = sbot_client.get_profile_info(ssb_id).await?;

    let name = profile_info.get("name");
    let description = profile_info.get("description");
    let image = profile_info.get("image");

    match (name, description, image) {
        (Some(name), Some(desc), Some(image)) => {
            println!(
                "peer {} is named {}. their profile image blob reference is {} and they describe themself as follows: {}",
                ssb_id, name, image, desc,
            )
        },
        (_, _, _) => {
            eprintln!("failed to retrieve all profile info values")
        }
    }

    Ok(())
}

pub async fn get_name_and_image(
    &mut self,
    ssb_id: &str
) -> Result<HashMap<String, String>, GolgiError>

Get the latest name and image values for a peer. This method can be used to display profile images of a list of users.

Example

use golgi::{Sbot, GolgiError};

async fn name_and_image_info() -> Result<(), GolgiError> {
    let mut sbot_client = Sbot::init(None, None).await?;

    let ssb_id = "@zqshk7o2Rpd/OaZ/MxH6xXONgonP1jH+edK9+GZb/NY=.ed25519";

    let profile_info = sbot_client.get_name_and_image(ssb_id).await?;

    let name = profile_info.get("name");
    let image = profile_info.get("image");

    match (name, image) {
        (Some(name), Some(image)) => {
            println!(
                "peer {} is named {}. their profile image blob reference is {}.",
                ssb_id, name, image,
            )
        },
        (Some(name), None) => {
            println!(
                "peer {} is named {}. no image blob reference was found for them.",
                ssb_id, name,
            )
        },
        (_, _) => {
            eprintln!("failed to retrieve all profile info values")
        }
    }

    Ok(())
}

pub async fn get_about_info(
    &mut self,
    ssb_id: &str,
    keys_to_search_for: Vec<&str>
) -> Result<HashMap<String, String>, GolgiError>

Get the latest values for the provided keys from the about type messages of a peer. The method will return once a value has been found for each key, or once all messages have been checked.

Example

use golgi::{Sbot, GolgiError};

async fn about_info() -> Result<(), GolgiError> {
    let mut sbot_client = Sbot::init(None, None).await?;

    let ssb_id = "@zqshk7o2Rpd/OaZ/MxH6xXONgonP1jH+edK9+GZb/NY=.ed25519";
    let keys_to_search_for = vec!["name", "description"];

    let about_info = sbot_client.get_about_info(ssb_id, keys_to_search_for).await?;

    let name = about_info.get("name");
    let description = about_info.get("description");

    match (name, description) {
        (Some(name), Some(desc)) => {
            println!(
                "peer {} is named {}. they describe themself as: {}",
                ssb_id, name, desc,
            )
        },
        (Some(name), None) => {
            println!(
                "peer {} is named {}. no description was found for them.",
                ssb_id, name,
            )
        },
        (_, _) => {
            eprintln!("failed to retrieve all profile info values")
        }
    }

    Ok(())
}

pub async fn get_name(
    &mut self,
    ssb_id: &str
) -> Result<Option<String>, GolgiError>

Get the latest name value for a peer.

Example

use golgi::{Sbot, GolgiError};

async fn name_info() -> Result<(), GolgiError> {
    let mut sbot_client = Sbot::init(None, None).await?;

    let ssb_id = "@zqshk7o2Rpd/OaZ/MxH6xXONgonP1jH+edK9+GZb/NY=.ed25519";

    if let Some(name) = sbot_client.get_name(ssb_id).await? {
        println!("peer {} is named {}", ssb_id, name)
    } else {
        eprintln!("no name found for peer {}", ssb_id)
    }

    Ok(())
}

pub async fn get_description(
    &mut self,
    ssb_id: &str
) -> Result<Option<String>, GolgiError>

Get the latest description value for a peer.

Example

use golgi::{Sbot, GolgiError};

async fn description_info() -> Result<(), GolgiError> {
    let mut sbot_client = Sbot::init(None, None).await?;

    let ssb_id = "@zqshk7o2Rpd/OaZ/MxH6xXONgonP1jH+edK9+GZb/NY=.ed25519";

    if let Some(desc) = sbot_client.get_description(ssb_id).await? {
        println!("peer {} describes themself as follows: {}", ssb_id, desc)
    } else {
        eprintln!("no description found for peer {}", ssb_id)
    }

    Ok(())
}

impl Sbot

pub async fn follow(&mut self, contact: &str) -> Result<String, GolgiError>

Follow a peer.

This is a convenience method to publish a contact message with following: true and blocking: false.

Example

use golgi::{Sbot, GolgiError};

async fn follow_peer() -> Result<(), GolgiError> {
    let mut sbot_client = Sbot::init(None, None).await?;

    let ssb_id = "@zqshk7o2Rpd/OaZ/MxH6xXONgonP1jH+edK9+GZb/NY=.ed25519";

    match sbot_client.follow(ssb_id).await {
        Ok(msg_ref) => {
            println!("follow msg reference is: {}", msg_ref)
        },
        Err(e) => eprintln!("failed to follow {}: {}", ssb_id, e)
    }

    Ok(())
}

pub async fn block(&mut self, contact: &str) -> Result<String, GolgiError>

Block a peer.

This is a convenience method to publish a contact message with following: false and blocking: true.

Example

use golgi::{Sbot, GolgiError};

async fn block_peer() -> Result<(), GolgiError> {
    let mut sbot_client = Sbot::init(None, None).await?;

    let ssb_id = "@zqshk7o2Rpd/OaZ/MxH6xXONgonP1jH+edK9+GZb/NY=.ed25519";

    match sbot_client.block(ssb_id).await {
        Ok(msg_ref) => {
            println!("block msg reference is: {}", msg_ref)
        },
        Err(e) => eprintln!("failed to block {}: {}", ssb_id, e)
    }

    Ok(())
}

pub async fn set_relationship(
    &mut self,
    contact: &str,
    following: bool,
    blocking: bool
) -> Result<String, GolgiError>

Publish a contact message defining the relationship for a peer.

Example

use golgi::{Sbot, GolgiError};

async fn relationship() -> Result<(), GolgiError> {
    let mut sbot_client = Sbot::init(None, None).await?;

    let ssb_id = "@zqshk7o2Rpd/OaZ/MxH6xXONgonP1jH+edK9+GZb/NY=.ed25519";
    let following = true;
    let blocking = false;

    match sbot_client.set_relationship(ssb_id, following, blocking).await {
        Ok(msg_ref) => {
            println!("contact msg reference is: {}", msg_ref)
        },
        Err(e) => eprintln!("failed to set relationship for {}: {}", ssb_id, e)
    }

    Ok(())
}

pub async fn friends_is_following(
    &mut self,
    args: RelationshipQuery
) -> Result<String, GolgiError>

Get the follow status of two peers (ie. does one peer follow the other?).

A RelationshipQuery struct must be defined and passed into this method.

Example

use golgi::{Sbot, GolgiError, api::friends::RelationshipQuery};

async fn relationship() -> Result<(), GolgiError> {
    let mut sbot_client = Sbot::init(None, None).await?;

    let peer_a = "@zqshk7o2Rpd/OaZ/MxH6xXONgonP1jH+edK9+GZb/NY=.ed25519";
    let peer_b = "@3QoWCcy46X9a4jTnOl8m3+n1gKfbsukWuODDxNGN0W8=.ed25519";

    let query = RelationshipQuery {
        source: peer_a.to_string(),
        dest: peer_b.to_string(),
    };

    match sbot_client.friends_is_following(query).await {
        Ok(following) if following == "true" => {
            println!("{} is following {}", peer_a, peer_b)
        },
        Ok(_) => println!("{} is not following {}", peer_a, peer_b),
        Err(e) => eprintln!("failed to query relationship status for {} and {}: {}", peer_a,
        peer_b, e)
    }

    Ok(())
}

pub async fn friends_is_blocking(
    &mut self,
    args: RelationshipQuery
) -> Result<String, GolgiError>

Get the block status of two peers (ie. does one peer block the other?).

A RelationshipQuery struct must be defined and passed into this method.

Example

use golgi::{Sbot, GolgiError, api::friends::RelationshipQuery};

async fn relationship() -> Result<(), GolgiError> {
    let mut sbot_client = Sbot::init(None, None).await?;

    let peer_a = "@zqshk7o2Rpd/OaZ/MxH6xXONgonP1jH+edK9+GZb/NY=.ed25519";
    let peer_b = "@3QoWCcy46X9a4jTnOl8m3+n1gKfbsukWuODDxNGN0W8=.ed25519";

    let query = RelationshipQuery {
        source: peer_a.to_string(),
        dest: peer_b.to_string(),
    };

    match sbot_client.friends_is_blocking(query).await {
        Ok(blocking) if blocking == "true" => {
            println!("{} is blocking {}", peer_a, peer_b)
        },
        Ok(_) => println!("{} is not blocking {}", peer_a, peer_b),
        Err(e) => eprintln!("failed to query relationship status for {} and {}: {}", peer_a,
        peer_b, e)
    }

    Ok(())
}

pub async fn get_follows(&mut self) -> Result<Vec<String>, GolgiError>

Get a list of peers followed by the local peer.

Example

use golgi::{Sbot, GolgiError};

async fn follows() -> Result<(), GolgiError> {
    let mut sbot_client = Sbot::init(None, None).await?;

    let follows = sbot_client.get_follows().await?;

    if follows.is_empty() {
        println!("we do not follow any peers")
    } else {
        follows.iter().for_each(|peer| println!("we follow {}", peer))
    }

    Ok(())
}

pub async fn friends_hops(
    &mut self,
    args: FriendsHops
) -> Result<Vec<String>, GolgiError>

Get a list of peers within the specified hops range.

A RelationshipQuery struct must be defined and passed into this method.

Hops = 0 returns a list of peers followed by the local identity. Those peers may or may not be mutual follows (ie. friends).

Hops = 1 includes the peers followed by the peers we follow. For example, if the local identity follows Aiko and Aiko follows Bridgette and Chris, hops = 1 will return a list including the public keys for Aiko, Bridgette and Chris (even though Bridgette and Chris are not followed by the local identity).

When reverse = True, hops = 0 should return a list of peers who follow the local identity, ie. followers (but this is not currently implemented in go-sbot).

Example

use golgi::{Sbot, GolgiError, api::friends::FriendsHops};

async fn peers_within_range() -> Result<(), GolgiError> {
    let mut sbot_client = Sbot::init(None, None).await?;

    let hops = 2;

    let query = FriendsHops {
        max: hops,
        reverse: Some(false),
        start: None,
    };

    let peers = sbot_client.friends_hops(query).await?;

    if peers.is_empty() {
        println!("no peers found within {} hops", hops)
    } else {
        peers.iter().for_each(|peer| println!("{} is within {} hops", peer, hops))
    }

    Ok(())
}

impl Sbot

pub async fn get_subset_stream(
    &mut self,
    query: SubsetQuery,
    options: Option<SubsetQueryOptions>
) -> Result<impl Stream<Item = Result<SsbMessageValue, GolgiError>>, GolgiError>

Make a subset query, as defined by the Subset replication for SSB specification.

Calls the partialReplication. getSubset RPC method.

Arguments

• query - A SubsetQuery which specifies the desired query filters.
• options - An Option<SubsetQueryOptions> which, if provided, adds additional specifications to the query, such as page limit and/or descending results.

Example

use async_std::stream::StreamExt;
use golgi::{
    Sbot,
    GolgiError,
    api::get_subset::{
        SubsetQuery,
        SubsetQueryOptions
    }
};

async fn query() -> Result<(), GolgiError> {
    let mut sbot_client = Sbot::init(None, None).await?;

    let post_query = SubsetQuery::Type {
        op: "type".to_string(),
        string: "post".to_string()
    };

    let post_query_opts = SubsetQueryOptions {
        descending: Some(true),
        keys: None,
        page_limit: Some(5),
    };

    // Return 5 `post` type messages from any author in descending order.
    let query_stream = sbot_client
        .get_subset_stream(post_query, Some(post_query_opts))
        .await?;

    // Iterate over the stream and pretty-print each returned message
    // value while ignoring any errors.
    query_stream.for_each(|msg| match msg {
        Ok(val) => println!("{:#?}", val),
        Err(_) => (),
    });

    Ok(())
}

impl Sbot

pub async fn create_history_stream(
    &mut self,
    id: String
) -> Result<impl Stream<Item = Result<SsbMessageValue, GolgiError>>, GolgiError>

Call the createHistoryStream RPC method.

Example

use async_std::stream::StreamExt;
use golgi::{Sbot, GolgiError};

async fn history() -> Result<(), GolgiError> {
    let mut sbot_client = Sbot::init(None, None).await?;

    let ssb_id = "@zqshk7o2Rpd/OaZ/MxH6xXONgonP1jH+edK9+GZb/NY=.ed25519".to_string();

    let history_stream = sbot_client.create_history_stream(ssb_id).await?;

    history_stream.for_each(|msg| {
        match msg {
            Ok(val) => println!("msg value: {:?}", val),
            Err(e) => eprintln!("error: {}", e),
        }
    }).await;

    Ok(())
}

impl Sbot

pub async fn invite_create(&mut self, uses: u16) -> Result<String, GolgiError>

Generate an invite code.

Calls the invite.create RPC method and returns the code.

Example

use golgi::{Sbot, GolgiError};

async fn invite_code_generator() -> Result<(), GolgiError> {
    let mut sbot_client = Sbot::init(None, None).await?;

    let invite_code = sbot_client.invite_create(5).await?;

    println!("this invite code can be used 5 times: {}", invite_code);

    Ok(())
}

pub async fn invite_use(
    &mut self,
    invite_code: &str
) -> Result<String, GolgiError>

Use an invite code.

Calls the invite.use RPC method and returns a reference to the follow message.

Example

use golgi::{Sbot, GolgiError};

async fn invite_code_consumer() -> Result<(), GolgiError> {
    let mut sbot_client = Sbot::init(None, None).await?;

    let invite_code = "127.0.0.1:8008:@0iMa+vP7B2aMrV3dzRxlch/iqZn/UM3S3Oo2oVeILY8=.ed25519~ZHNjeajPB/84NjjsrglZInlh46W55RcNDPcffTPgX/Q=";
     
    match sbot_client.invite_use(invite_code).await {
        Ok(msg_ref) => println!("consumed invite code. msg reference: {}", msg_ref),
        Err(e) => eprintln!("failed to consume the invite code: {}", e),
    }

    Ok(())
}

impl Sbot

pub async fn publish(
    &mut self,
    msg: SsbMessageContent
) -> Result<String, GolgiError>

Publish a message.

Arguments

• msg - A SsbMessageContent enum whose variants include Pub, Post, Contact, About, Channel and Vote.

Example

use golgi::{Sbot, GolgiError, messages::SsbMessageContent};

async fn publish_a_msg() -> Result<(), GolgiError> {
    let mut sbot_client = Sbot::init(None, None).await?;

    // Construct an SSB message of type `post`.
    let post = SsbMessageContent::Post {
        text: "And then those vesicles, filled with the Golgi products, move to the rest of the cell".to_string(),
        mentions: None,
    };

    let msg_ref = sbot_client.publish(post).await?;

    println!("msg reference for the golgi post: {}", msg_ref);

    Ok(())
}

pub async fn publish_post(&mut self, text: &str) -> Result<String, GolgiError>

Publish a post.

Convenient wrapper around the publish method which constructs and publishes a post type message appropriately from a string.

Example

use golgi::{Sbot, GolgiError};

async fn publish_a_post() -> Result<(), GolgiError> {
    let mut sbot_client = Sbot::init(None, None).await?;

    let text = "The Golgi is located right near the nucleus.";

    let msg_ref = sbot_client.publish_post(text).await?;

    println!("msg reference for the golgi post: {}", msg_ref);

    Ok(())
}

pub async fn publish_description(
    &mut self,
    description: &str
) -> Result<String, GolgiError>

Publish a description for the local identity.

Convenient wrapper around the publish method which constructs and publishes an about type description message appropriately from a string.

Example

use golgi::{Sbot, GolgiError};

async fn publish_a_description() -> Result<(), GolgiError> {
    let mut sbot_client = Sbot::init(None, None).await?;

    let description = "The Golgi apparatus was identified by the Italian scientist Camillo Golgi in 1897.";

    let msg_ref = sbot_client.publish_description(description).await?;

    println!("msg reference for the golgi description: {}", msg_ref);

    Ok(())
}

pub async fn publish_name(&mut self, name: &str) -> Result<String, GolgiError>

Publish a name for the local identity.

Convenient wrapper around the publish method which constructs and publishes an about type name message appropriately from a string.

Example

use golgi::{Sbot, GolgiError};

async fn publish_a_name() -> Result<(), GolgiError> {
    let mut sbot_client = Sbot::init(None, None).await?;

    let name = "glyphski_golgionikus";

    let msg_ref = sbot_client.publish_name(name).await?;

    println!("msg reference: {}", msg_ref);

    Ok(())
}

impl Sbot

pub async fn whoami(&mut self) -> Result<String, GolgiError>

Get the public key of the local identity.

Example

use golgi::{Sbot, GolgiError};

async fn fetch_id() -> Result<(), GolgiError> {
    let mut sbot_client = Sbot::init(None, None).await?;

    let pub_key = sbot_client.whoami().await?;

    println!("local ssb id: {}", pub_key);

    Ok(())
}

impl Sbot

pub async fn init(
    ip_port: Option<String>,
    net_id: Option<String>
) -> Result<Sbot, GolgiError>

Initiate a connection with an sbot instance. Define the IP address, port and network key for the sbot, then retrieve the public key, private key (secret) and identity from the .ssb-go/secret file.

pub async fn get_sbot_connection(&self) -> Result<SbotConnection, GolgiError>

Creates a new connection with the sbot, using the address, network_id, public_key and private_key supplied when Sbot was initialized.

Note that a single Sbot can have multiple SbotConnection at the same time.