Async Mastodon client library

[]

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

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(())
}