Crate egg_mode

Expand description

A library for interacting with Twitter.

egg-mode is a Twitter library that aims to make as few assumptions about the user’s codebase as possible. Endpoints are exposed as bare functions where authentication details are passed in as arguments, rather than as builder functions of a root “service” manager. The only exceptions to this guideline are endpoints with many optional parameters, like posting a status update or updating the metadata of a list.

About the examples in this documentation

There are a couple prerequisites to using egg-mode, which its examples also assume:

All methods that hit the twitter API are async and should be awaited with the .await syntax. All such calls return a result type with the Error enum as their Error value. The resulting future must be executed on a tokio executor. For more information, check out the Rust async book and the Tokio documentation guides.
Twitter tracks API use through “tokens” which are managed by Twitter and processed separately for each “authenticated user” you wish to connect to your app. egg-mode represents these through the Token type, which each function that connects to the API uses to authenticate the call. egg-mode’s authentication overview describes how you can obtain one of these, but each example outside of the authentication documentation brings in a Token “offscreen”, to avoid distracting from the rest of the example.

To load the profile information of a single user:

let rustlang = egg_mode::user::show("rustlang", &token).await.unwrap();

println!("{} (@{})", rustlang.name, rustlang.screen_name);

To post a new tweet:

use egg_mode::tweet::DraftTweet;

let post = DraftTweet::new("Hey Twitter!").send(&token).await.unwrap();

Crate features

While all of egg-mode’s features are available by default, it allows you to configure how it connects to Twitter and how it uses HTTPS. The crate’s Cargo features are the following:

native_tls: On by default. With this feature on, egg-mode uses native-tls to access your operating system’s native TLS functionality to access Twitter.
rustls: Off by default. With this feature on, egg-mode instead uses the rustls TLS stack to access Twitter. rustls will still use your operating system’s native root certificates to verify the connection.
rustls_webpki: Off by default. With this feature on, egg-mode will also use rustls to connect, but it will also use the webpki-roots crate to include a set of compiled-in root certificates to verify the connection, instead of using your operating system’s root certificates.

Keep in mind that these features are mutually exclusive - if you enable more than one, a compile error will result. If you need to use rustls or rustls_webpki, remember to set default-features = false in your Cargo.toml.

Types and Functions

All of the main content of egg-mode is in submodules, but there are a few things here in the crate root. To wit, it contains items related to authentication and a couple items that all the submodules use.

`Response<T>`

Every method that calls Twitter and carries rate-limit information wraps its return value in a Response struct, that transmits this information to your app. From there, you can handle the rate-limit information to hold off on that kind of request, or simply grab its response field to get the output of whatever method you called. Response also implements Deref, so for the most part you can access fields of the final result without having to grab the response field directly.

`Token`

While the complete process of authenticating with Twitter involves functions and types in the auth module, the Token type is central enough to the operation of egg-mode that it’s re-exported at the crate root. The inner KeyPair type is also re-exported here, to aid existing code that used the type, and to aid the authentication process, which requires manually creating one at the very beginning.

Modules

As there are many actions available in the Twitter API, egg-mode divides them roughly into several modules by their shared purpose. Here’s a sort of high-level overview, in rough order from “most important” to “less directly used”:

Primary actions

These could be considered the “core” actions within the Twitter API that egg-mode has made available.

auth: This module contains all the functions required to fully authenticate with Twitter. The module docs contain the complete overview of how to use egg-mode to properly sign your API calls so that Twitter will accept them.
tweet: This module lets you act on tweets. Here you can find actions to load a user’s timeline, post a new tweet, or like and retweet individual posts.
user: This module lets you act on users, be it by following or unfollowing them, loading their profile information, blocking or muting them, or showing the relationship between two users.
search: Due to the complexity of searching for tweets, it gets its own module.
direct: Here you can work with a user’s Direct Messages, either by loading DMs they’ve sent or received, or by sending new ones.
list: This module lets you act on lists, from creating and deleting them, adding and removing users, or loading the posts made by their members.
media: This module lets you upload images, GIFs, and videos to Twitter so you can attach them to tweets.

Secondary actions

These modules still contain direct actions for Twitter, but they can be considered as having more of a helper role than something you might use directly.

place: Here are actions that look up physical locations that can be attached to tweets, as well at the Place struct that appears on tweets with locations attached.
service: These are some miscellaneous methods that show information about the Twitter service as a whole, like loading the maximum length of t.co URLs or loading the current Terms of Service or Privacy Policy.

Helper structs

These modules contain some implementations that wrap some pattern seen in multiple “action” modules.

cursor: This contains a helper trait and some helper structs that allow effective cursoring through certain collections of results from Twitter.
entities: Whenever some text can be returned that may contain links, hashtags, media, or user mentions, its metadata is parsed into something that lives in this module.
error: Any interaction with Twitter may result in an error condition, be it from finding a tweet or user that doesn’t exist or the network connection being unavailable. All the error types are aggregated into an enum in this module.