Crate chorus

Expand description

Chorus combines all the required functionalities of a user-centric Spacebar library into one package. The library handles various aspects on your behalf, such as rate limiting, authentication and maintaining a WebSocket connection to the Gateway. This means that you can focus on building your application, instead of worrying about the underlying implementation details.

Establishing a Connection

To connect to a Spacebar compatible server, you need to create an Instance like this:

use chorus::instance::Instance;
use chorus::UrlBundle;

#[tokio::main]
async fn main() {
    let bundle = UrlBundle::new(
        "https://example.com/api".to_string(),
        "wss://example.com/".to_string(),
        "https://example.com/cdn".to_string(),
    );
    let instance = Instance::new(bundle)
        .await
        .expect("Failed to connect to the Spacebar server");
    // You can create as many instances of `Instance` as you want, but each `Instance` should likely be unique.
    dbg!(instance.instance_info);
    dbg!(instance.limits_information);
}

This Instance can now be used to log in, register and from there on, interact with the server in all sorts of ways.

Logging In

Logging in correctly provides you with an instance of ChorusUser, with which you can interact with the server and manipulate the account. Assuming you already have an account on the server, you can log in like this:

use chorus::types::LoginSchema;
// Assume, you already have an account created on this instance. Registering an account works
// the same way, but you'd use the Register-specific Structs and methods instead.
let login_schema = LoginSchema {
    login: "user@example.com".to_string(),
    password: "Correct-Horse-Battery-Staple".to_string(),
    ..Default::default()
};
// Each user connects to the Gateway. The Gateway connection lives on a seperate thread. Depending on
// the runtime feature you choose, this can potentially take advantage of all of your computers' threads.
let user = instance
    .login_account(login_schema)
    .await
    .expect("An error occurred during the login process");
dbg!(user.belongs_to);
dbg!(&user.object.read().unwrap().username);

Supported Platforms

All major desktop operating systems (Windows, macOS (aarch64/x86_64), Linux (aarch64/x86_64)) are supported. wasm32-unknown-unknown is a supported compilation target on versions 0.12.0 and up. This allows you to use Chorus in your browser, or in any other environment that supports WebAssembly.

We recommend checking out the examples directory, as well as the documentation for more information.

MSRV (Minimum Supported Rust Version)

Rust 1.67.1. This number might change at any point while Chorus is not yet at version 1.0.0.

Development Setup

Make sure that you have at least Rust 1.67.1 installed. You can check your Rust version by running cargo --version in your terminal. To compile for wasm32-unknown-unknown, you need to install the wasm32-unknown-unknown target. You can do this by running rustup target add wasm32-unknown-unknown.

Testing

In general, the tests will require you to run a local instance of the Spacebar server. You can find instructions on how to do that here. You can find a pre-configured version of the server here. It is recommended to use the pre-configured version, as certain things like “proxy connection checking” are already disabled on this version, which otherwise might break tests.

api
All of the API’s endpoints.
errors
Contains all the errors that can be returned by the library.
gateway
instance
Instance and ChorusUser objects.
ratelimiter
Ratelimiter and request handling functionality.
types
All the types, entities, events and interfaces of the Spacebar API.
voice
Where the voice chat implementation will be, once it’s finished. For development on voice, see the feature/voice branch.

Structs

UrlBundle
A URLBundle bundles together the API-, Gateway- and CDN-URLs of a Spacebar instance.