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

clarify api descriptions for about msgs

This commit is contained in:
glyph 2022-02-14 12:23:10 +02:00
parent 1c434193eb
commit 9c959346f1
1 changed files with 88 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

120
src/api/about.rs
View File

@ -23,7 +23,36 @@ use crate::{
};
impl Sbot {
/// Get the about messages for a particular peer in order of recency.
/// Get all the `about` type messages for a peer in order of recency
/// (ie. most recent messages first).
///
/// # Example
///
/// ```rust
/// use async_std::stream::{Stream, StreamExt};
/// use futures::pin_mut;
/// 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.
/// 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_about_message_stream(
&mut self,
ssb_id: &str,
@ -32,13 +61,16 @@ impl Sbot {
op: "author".to_string(),
feed: ssb_id.to_string(),
};
// specify that most recent messages should be returned first
let query_options = SubsetQueryOptions {
descending: Some(true),
keys: None,
page_limit: None,
};
let get_subset_stream = self.get_subset_stream(query, Some(query_options)).await?;
// TODO: after fixing sbot regression,
// change this subset query to filter by type about in addition to author
// and remove this filter section
@ -47,11 +79,13 @@ impl Sbot {
Ok(val) => val.is_message_type(SsbMessageContentType::About),
Err(_err) => false,
});
// return about message stream
Ok(about_message_stream)
}
/// Get value of latest about message with given key for given peer.
/// Get the value of the latest `about` type message, containing the given
/// `key`, for a peer.
pub async fn get_latest_about_message(
&mut self,
ssb_id: &str,
@ -59,9 +93,13 @@ impl Sbot {
) -> Result<Option<String>, GolgiError> {
// get about_message_stream
let about_message_stream = self.get_about_message_stream(ssb_id).await?;
// now we have a stream of about messages with most recent at the front of the vector
// now we have a stream of about messages with most recent at the front
// of the vector
pin_mut!(about_message_stream);
// iterate through the vector looking for most recent about message with the given key
// iterate through the vector looking for most recent about message with
// the given key
let latest_about_message_res: Option<Result<SsbMessageValue, GolgiError>> =
about_message_stream
// find the first msg that contains the field `key`
@ -70,8 +108,10 @@ impl Sbot {
Err(_) => false,
})
.await;
// Option<Result<SsbMessageValue, GolgiError>> -> Option<SsbMessageValue>
let latest_about_message = latest_about_message_res.and_then(|msg| msg.ok());
// Option<SsbMessageValue> -> Option<String>
let latest_about_value = latest_about_message.and_then(|msg| {
msg
@ -83,11 +123,13 @@ impl Sbot {
// Option<&str> -> Option<String>
.map(|value| value.to_string())
});
// return value is either `Ok(Some(String))` or `Ok(None)`
Ok(latest_about_value)
}
/// Get HashMap of profile info for a peer as defined by the given ID.
/// Get the latest `name`, `description` and `image` values for a peer,
/// as defined in their `about` type messages.
pub async fn get_profile_info(
&mut self,
ssb_id: &str,
@ -96,8 +138,8 @@ impl Sbot {
self.get_about_info(ssb_id, keys_to_search_for).await
}
/// Get HashMap of name and image for given peer
/// (this is can be used to display profile images of a list of users).
/// Get the latest `name` and `image` values for a peer. This method can
/// be used to display profile images of a list of users.
pub async fn get_name_and_image(
&mut self,
ssb_id: &str,
@ -106,18 +148,34 @@ 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 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.
///
/// # Arguments
/// # Example
///
/// * `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.
/// ```rust
/// 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?;
///
/// for (name, desc) in about_info {
/// println!(
/// "peer {} is named {} and describes themself as follows: {}",
/// ssb_id, name, desc,
/// );
/// }
///
///
/// Ok(())
/// }
/// ```
pub async fn get_about_info(
&mut self,
ssb_id: &str,
@ -125,9 +183,15 @@ impl Sbot {
) -> Result<HashMap<String, String>, GolgiError> {
// get about_message_stream
let about_message_stream = self.get_about_message_stream(ssb_id).await?;
// now we have a stream of about messages with most recent at the front of the vector
pin_mut!(about_message_stream); // needed for iteration
// now we have a stream of about messages with most recent at the front
// of the vector
// `pin_mut!` is needed for iteration
pin_mut!(about_message_stream);
let mut profile_info: HashMap<String, String> = HashMap::new();
// iterate through the stream while it still has more values and
// we still have keys we are looking for
while let Some(res) = about_message_stream.next().await {
@ -150,7 +214,8 @@ impl Sbot {
Some(val) => {
// if a value is found, then insert it
profile_info.insert(key.to_string(), val);
// remove this key fom keys_to_search_for, since we are no longer searching for it
// remove this key from keys_to_search_for,
// since we are no longer searching for it
keys_to_search_for.retain(|val| val != key)
}
None => continue,
@ -163,25 +228,16 @@ impl Sbot {
}
}
}
Ok(profile_info)
}
/// Get latest name for the given peer.
///
/// # Arguments
///
/// * `ssb_id` - A reference to a string slice which represents the SSB ID
/// to lookup the about name for.
/// Get the latest `name` value for a peer.
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 description for the given peer.
///
/// # Arguments
///
/// * `ssb_id` - A reference to a string slice which represents the SSB ID
/// to lookup the about description for.
/// Get the latest `description` value for a peer.
pub async fn get_description(&mut self, ssb_id: &str) -> Result<Option<String>, GolgiError> {
self.get_latest_about_message(ssb_id, "description").await
}