golgi-ssb
/
golgi
4
5
Fork 0
Code Issues 11 Pull Requests 1 Projects 1 Releases Wiki Activity

add docs for each api module

This commit is contained in:
glyph 2022-02-08 11:52:52 +02:00
parent ebb92aba24
commit de6689220e
8 changed files with 99 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

47
src/api/about.rs
View File

@ -1,3 +1,15 @@
//! Retrieve data about a peer.
//!
//! Implements the following methods:
//!
//! - [`Sbot::get_about_info`]
//! - [`Sbot::get_about_message_stream`]
//! - [`Sbot::get_description`]
//! - [`Sbot::get_latest_about_message`]
//! - [`Sbot::get_name`]
//! - [`Sbot::get_name_and_image`]
//! - [`Sbot::get_profile_info`]
use std::collections::HashMap;
use async_std::stream::{Stream, StreamExt};
@ -11,7 +23,7 @@ use crate::{
};
impl Sbot {
/// Get the about messages for a particular user in order of recency.
/// Get the about messages for a particular peer in order of recency.
pub async fn get_about_message_stream(
&mut self,
ssb_id: &str,
@ -39,7 +51,7 @@ impl Sbot {
Ok(about_message_stream)
}
/// Get value of latest about message with given key from given user
/// Get value of latest about message with given key for given peer.
pub async fn get_latest_about_message(
&mut self,
ssb_id: &str,
@ -75,7 +87,7 @@ impl Sbot {
Ok(latest_about_value)
}
/// Get HashMap of profile info for given user
/// Get HashMap of profile info for a peer as defined by the given ID.
pub async fn get_profile_info(
&mut self,
ssb_id: &str,
@ -84,8 +96,8 @@ impl Sbot {
self.get_about_info(ssb_id, keys_to_search_for).await
}
/// Get HashMap of name and image for given user
/// (this is can be used to display profile images of a list of users)
/// Get HashMap of name and image for given peer
/// (this is can be used to display profile images of a list of users).
pub async fn get_name_and_image(
&mut self,
ssb_id: &str,
@ -94,17 +106,18 @@ impl Sbot {
self.get_about_info(ssb_id, keys_to_search_for).await
}
/// Get HashMap of about keys to values for given user
/// by iteratively searching through a stream of about messages,
/// in order of recency,
/// until we find all about messages for all needed info
/// or reach the end of the stream.
/// Get HashMap of about keys to values for given user by iteratively
/// searching through a stream of about messages, in order of recency,
/// until we find all about messages for all needed info or reach the end
/// of the stream.
///
/// # Arguments
///
/// * `ssb_id` - A reference to a string slice which represents the id of the user to get info about.
/// * `keys_to_search_for` - A mutable vector of string slice, which represent the about keys
/// that will be searched for. As they are found, keys are removed from the vector.
/// * `ssb_id` - A reference to a string slice which represents the id of
/// the user to get info about.
/// * `keys_to_search_for` - A mutable vector of string slice, which
/// represent the about keys that will be searched for. As they are found,
/// keys are removed from the vector.
pub async fn get_about_info(
&mut self,
ssb_id: &str,
@ -153,21 +166,21 @@ impl Sbot {
Ok(profile_info)
}
/// Get latest about name from given user
/// Get latest name for the given peer.
///
/// # Arguments
///
/// * `ssb_id` - A reference to a string slice which represents the ssb user
/// * `ssb_id` - A reference to a string slice which represents the SSB ID
/// to lookup the about name for.
pub async fn get_name(&mut self, ssb_id: &str) -> Result<Option<String>, GolgiError> {
self.get_latest_about_message(ssb_id, "name").await
}
/// Get latest about description from given user
/// Get latest description for the given peer.
///
/// # Arguments
///
/// * `ssb_id` - A reference to a string slice which represents the ssb user
/// * `ssb_id` - A reference to a string slice which represents the SSB ID
/// to lookup the about description for.
pub async fn get_description(&mut self, ssb_id: &str) -> Result<Option<String>, GolgiError> {
self.get_latest_about_message(ssb_id, "description").await

40
src/api/friends.rs
View File

@ -1,23 +1,35 @@
use crate::{
api::{FriendsHops, RelationshipQuery},
error::GolgiError,
messages::SsbMessageContent,
sbot::Sbot,
utils,
};
//! Define peer relationships and query the social graph.
//!
//! Implements the following methods:
//!
//! - [`Sbot::block`]
//! - [`Sbot::follow`]
//! - [`Sbot::friends_hops`]
//! - [`Sbot::friends_is_blocking`]
//! - [`Sbot::friends_is_following`]
//! - [`Sbot::get_follows`]
//! - [`Sbot::set_relationship`]
use crate::{error::GolgiError, messages::SsbMessageContent, sbot::Sbot, utils};
// re-export friends-related kuska types
pub use kuska_ssb::api::dto::content::{FriendsHops, RelationshipQuery};
impl Sbot {
/// Convenience method to set a relationship with following: true, blocking: false.
/// Convenience method to set a relationship with following: `true`,
/// blocking: `false`.
pub async fn follow(&mut self, contact: &str) -> Result<String, GolgiError> {
self.set_relationship(contact, true, false).await
}
/// Convenience method to set a relationship with following: false, blocking: true.
/// Convenience method to set a relationship with following: `false`,
/// blocking: `true`.
pub async fn block(&mut self, contact: &str) -> Result<String, GolgiError> {
self.set_relationship(contact, false, true).await
}
/// Publishes a contact relationship to the given user (with ssb_id) with the given state.
/// Publish a contact relationship to the given peer (with ssb_id) with
/// the given state.
pub async fn set_relationship(
&mut self,
contact: &str,
@ -34,7 +46,7 @@ impl Sbot {
}
/// Call the `friends isFollowing` RPC method and return a message reference.
/// Returns true if src_id is following dest_id and false otherwise.
/// Returns `true` if `src_id` is following `dest_id` and `false` otherwise.
pub async fn friends_is_following(
&mut self,
args: RelationshipQuery,
@ -54,7 +66,7 @@ impl Sbot {
}
/// Call the `friends isblocking` RPC method and return a message reference.
/// Returns true if src_id is blocking dest_id and false otherwise.
/// Returns `true` if `src_id` is blocking `dest_id` and `false` otherwise.
pub async fn friends_is_blocking(
&mut self,
args: RelationshipQuery,
@ -86,7 +98,7 @@ impl Sbot {
// Gets a Vec<String> where each element is a peer who follows you
/// TODO: currently this method is not working
/// go-sbot does not seem to listen to the reverse=True parameter
/// and just returns follows
/// and just returns follows.
async fn _get_followers(&mut self) -> Result<Vec<String>, GolgiError> {
self.friends_hops(FriendsHops {
max: 1,
@ -100,7 +112,7 @@ impl Sbot {
/// where each element of the vector is the ssb_id of a peer.
///
/// When opts.reverse = True, it should return peers who are following you
/// (but this is currently not working)
/// (but this is currently not working).
pub async fn friends_hops(&mut self, args: FriendsHops) -> Result<Vec<String>, GolgiError> {
let mut sbot_connection = self.get_sbot_connection().await?;
let req_id = sbot_connection.client.friends_hops_req_send(args).await?;

13
src/api/get_subset.rs
View File

@ -1,9 +1,14 @@
//! Perform subset queries.
//!
//! Implements the following methods:
//!
//! - [`Sbot::get_subset_stream`]
use async_std::stream::Stream;
use crate::{
error::GolgiError, messages::SsbMessageValue, sbot::Sbot, utils, utils::get_source_stream,
};
use crate::{error::GolgiError, messages::SsbMessageValue, sbot::Sbot, utils};
// re-export subset-related kuska types
pub use kuska_ssb::api::dto::content::{SubsetQuery, SubsetQueryOptions};
impl Sbot {
@ -25,7 +30,7 @@ impl Sbot {
.client
.getsubset_req_send(query, options)
.await?;
let get_subset_stream = get_source_stream(
let get_subset_stream = utils::get_source_stream(
sbot_connection.rpc_reader,
req_id,
utils::ssb_message_res_parse,

6
src/api/history_stream.rs
View File

@ -1,3 +1,9 @@
//! Return a history stream.
//!
//! Implements the following methods:
//!
//! - [`Sbot::create_history_stream`]
use async_std::stream::Stream;
use kuska_ssb::api::dto::CreateHistoryStreamIn;

7
src/api/invite.rs
View File

@ -1,3 +1,10 @@
//! Create and use invite codes.
//!
//! Implements the following methods:
//!
//! - [`Sbot::invite_create`]
//! - [`Sbot::invite_use`]
use crate::{error::GolgiError, sbot::Sbot, utils};
impl Sbot {

16
src/api/mod.rs
View File

@ -1,12 +1,10 @@
//! API for interacting with a running go-sbot instance.
mod about;
mod friends;
mod get_subset;
mod history_stream;
mod invite;
mod publish;
mod whoami;
pub mod about;
pub mod friends;
pub mod get_subset;
pub mod history_stream;
pub mod invite;
pub mod publish;
pub mod whoami;
pub use crate::sbot::*;
pub use kuska_ssb::api::dto::content::{FriendsHops, RelationshipQuery};

9
src/api/publish.rs
View File

@ -1,3 +1,12 @@
//! Publish Scuttlebutt messages.
//!
//! Implements the following methods:
//!
//! - [`Sbot::publish`]
//! - [`Sbot::publish_description`]
//! - [`Sbot::publish_name`]
//! - [`Sbot::publish_post`]
use crate::{error::GolgiError, messages::SsbMessageContent, sbot::Sbot, utils};
impl Sbot {

6
src/api/whoami.rs
View File

@ -1,4 +1,8 @@
//! Sbot type and associated methods.
//! Return the SSB ID of the local sbot instance.
//!
//! Implements the following methods:
//!
//! - [`Sbot::whoami`]
use crate::{error::GolgiError, sbot::Sbot, utils};