Repository files navigation

Chorus

Explore the docs »

Report Bug ·crates.io ·Join Discord

Chorus is a Rust library which poses as an API wrapper forSpacebar Chat,Discord and our own Polyphony. Its high-level API is designed to be easy to use, while still providing theflexibility 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.

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 maintaininga 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 yourCargo.toml file:

[dependencies]chorus ="0.19.0"

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

use chorus::instance::Instance;#[tokio::main]asyncfnmain(){let instance =Instance::new("https://example.com",None).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 correctly provides you with an instance ofChorusUser, with which you can interact with the server andmanipulate 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.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);

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 versions0.12.0 and up. This allows you to useChorus in your browser, or in any other environment that supports WebAssembly.

To compile forwasm32-unknown-unknown, execute the following command:

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

The following features are supported onwasm32-unknown-unknown:

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

Rust1.71.1. This number might change at any point while Chorus is not yet at version 1.0.0.

Make sure that you have at least Rust 1.71.1 installed. You can check your Rust version by runningcargo --versionin your terminal. To compile forwasm32-unknown-unknown, you need to install thewasm32-unknown-unknown target.You can do this by runningrustup target add wasm32-unknown-unknown.

In general, the tests will require you to run a local instance of the Spacebar server. You can find instructions on howto do thathere. You can find a pre-configured version of the serverhere. It is recommended to use the pre-configured version, as certain thingslike "proxy connection checking" are already disabled on this version, which otherwise might break tests.

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

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

Code gated behind thebackend feature is not considered part of the public API and can change withoutaffecting semver compatibility. Thebackend feature is explicitly meant for use insymfonia

SeeCONTRIBUTING.md.