Chorus

Explore the docs »

Report Bug · crates.io · Join Zulip

Chorus is a Rust library which poses as an API wrapper for Spacebar Chat, Discord and our own Polyphony. Its high-level API is designed to be easy to use, while still providing the flexibility one would expect from a library like this.

You can establish as many connections to as many servers as you want, and you can use them all at the same time.

A Tour of Chorus

Chorus combines all the required functionalities of an API wrapper for chat services into one modular library. 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.

To get started with Chorus, import it into your project by adding the following to your Cargo.toml file:

[dependencies]
chorus = "0.20.0"

Establishing a Connection

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

use chorus::{instance::Instance, types::IntoShared};

#[tokio::main]
async fn main() {

    // This instance will later need to be shared across threads and users, so we'll
    // store it inside of the `Shared` type (note the `into_shared()` method call)
    let instance = Instance::new("https://example.com")
        .await
        .expect("Failed to connect to the Spacebar server")
		.into_shared();

    // You can create as many instances of `Instance` as you want, but each `Instance` should likely be unique.

    // Each time we want to access the underlying `Instance` we need to lock
    // its reference so other threads don't modify the data while we're reading or changing it
    let instance_lock = instance.read().unwrap();

    dbg!(&instance_lock.instance_info);
    dbg!(&instance_lock.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. Each users' Gateway connection lives on a separate thread. Depending on
// the runtime feature you choose, this can potentially take advantage of all of your computers' threads.
//
// Note that we clone the reference to the instance here, not the instance itself
// (we do this because each user needs its own access to the instance's data)
let user = Instance::login_account(instance.clone(), 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.

To compile for wasm32-unknown-unknown, execute the following command:

cargo build --target=wasm32-unknown-unknown --no-default-features

The following features are supported on wasm32-unknown-unknown:

Feature	WASM Support
client	✅
rt	✅
rt-multi-thread	❌
backend	❌
voice	❌
voice_udp	❌
voice_gateway	✅

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

MSRV (Minimum Supported Rust Version)

Rust 1.81.0. 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.81.0 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.

wasm

To test for wasm, you will need to cargo install wasm-pack. You can then run wasm-pack test --<chrome/firefox/safari> --headless -- --target wasm32-unknown-unknown --features="rt, client, voice_gateway" --no-default-features to run the tests for wasm.

Versioning

Like other cargo crates, this crate uses Semantic Versioning 2.0.0 as its versioning scheme. You can read the specification here.

Code gated behind the backend feature is not considered part of the public API and can change without affecting semver compatibility. The backend feature is explicitly meant for use in symfonia

Branches

This repository operates with two branches of heightened importance:

• dev (default): The unstable but very latest version of chorus, including the newest features and patches.
• stable: As the name suggests, a stable and thoroughly tested version of chorus. The state of this branch is equal to the latest release version of chorus on crates.io.

When opening a PR, please target the dev branch. Once considered ready for release, all changes on dev will be merged into stable, creating a new, tagged release in the process.

Contributing

See CONTRIBUTING.md.