1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
|
# Async Mastodon client library
[]
[](https://crates.io/crates/mastodon-async)
[](https://docs.rs/mastodon-async)
[](https://crates.io/crates/mastodon-async)
[Documentation](https://docs.rs/mastodon-async/)
A type-safe, async wrapper around the client [API](https://docs.joinmastodon.org/client/intro/)
for [Mastodon](https://botsin.space/)
## Installation
To add `mastodon-async` to your project, add the following to the
`[dependencies]` section of your `Cargo.toml`
```toml
mastodon-async = "1.0"
```
Alternatively, run the following command:
~~~console
$ cargo add mastodon-async
~~~
### Use Rustls instead of OpenSSL
To use Rustls instead of OpenSSL for HTTPS request, define the dependency as follows
```toml
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:
```rust,ignore
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:
```toml
[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")]`.
<!--
todo swap ignore with no_run just below here & the next example
test passes locally but not in CI
-->
```rust,ignore
// 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](https://docs.joinmastodon.org/api/streaming):
> **Note**: this example compiles, but will not run. See the
> [log_events](https://github.com/dscottboggs/mastodon-async/blob/main/examples/log_events.rs)
> example for a more thorough example which does compile and run.
```rust,ignore
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(())
}
```
|
