mastodon-async

Crates.iomastodon-async
lib.rsmastodon-async
version1.3.2
sourcesrc
created_at2022-12-23 17:37:30.420263
updated_at2024-02-09 11:30:33.421093
descriptionA wrapper around the Mastodon API.
homepage
repositoryhttps://github.com/dscottboggs/mastodon-async.git
max_upload_size
id744638
size291,571
Scott Boggs (dscottboggs)

documentation

README

Async Mastodon client library

[Build Status] crates.io Docs MIT/APACHE-2.0

Documentation

A type-safe, async wrapper around the client API for Mastodon

Installation

To add mastodon-async to your project, add the following to the [dependencies] section of your Cargo.toml

mastodon-async = "1.0"

Alternatively, run the following command:

$ cargo add mastodon-async

Use Rustls instead of OpenSSL

To use Rustls instead of OpenSSL for HTTPS request, define the dependency as follows

mastodon-async = { version = "1", default-features = false, features = ["rustls-tls"] }

A Note on Debugging

This library offers structured logging. To get better information about bugs or how something is working, I recommend adding the femme crate as a dependency, then adding this line to the beginning of your main() function:

femme::with_level(log::LevelFilter::Trace);

When compiling for the debug target, this offers a mostly-human-readable output with a lot of details about what's happening. When targeting release, JSON- structured metadata is offered, which can be filtered and manipulated with scripts or at the shell with jq.

There are other crates which make use of the log crate's new (unstable) kv features, this is just the one that works for me for now.

Example

In your Cargo.toml, make sure you enable the toml feature:

[dependencies.mastodon-async]
version = "1.0"
features = ["toml", "mt"]

The "mt" feature is for tokio multi-threaded. For single threaded, drop the "mt" feature and replace #[tokio::main] with #[tokio::main(flavor = "current_thread")].

// src/main.rs

use mastodon_async::prelude::*;
use mastodon_async::helpers::toml; // requires `features = ["toml"]`
use mastodon_async::{helpers::cli, Result};

#[tokio::main] // requires `features = ["mt"]
async fn main() -> Result<()> {
    let mastodon = if let Ok(data) = toml::from_file("mastodon-data.toml") {
        Mastodon::from(data)
    } else {
        register().await?
    };

    let you = mastodon.verify_credentials().await?;

    println!("{:#?}", you);

    Ok(())
}

async fn register() -> Result<Mastodon> {
    let registration = Registration::new("https://botsin.space")
                                    .client_name("mastodon-async-examples")
                                    .build()
                                    .await?;
    let mastodon = cli::authenticate(registration).await?;

    // Save app data for using on the next run.
    toml::to_file(&mastodon.data, "mastodon-data.toml")?;

    Ok(mastodon)
}

It also supports the Streaming API:

Note: this example compiles, but will not run. See the log_events example for a more thorough example which does compile and run.

use mastodon_async::{prelude::*, Result, entities::event::Event};
use futures_util::TryStreamExt;

#[tokio::main]
async fn main() -> Result<()> {
    let client = Mastodon::from(Data::default());

    client.stream_user()
        .await?
        .try_for_each(|event| async move {
            match event {
                Event::Update(ref status) => { /* .. */ },
                Event::Notification(ref notification) => { /* .. */ },
                Event::Delete(ref id) => { /* .. */ },
                Event::FiltersChanged => { /* .. */ },
            }
            Ok(())
        })
        .await?;
    Ok(())
}
Commit count: 224

cargo fmt