3e22b5c0ed
* add WebSocketEvent macro derive, bump chorus-macros to 0.3.0 (#490) * feat: add WebSocketEvent derive, bump to 0.2.1 * change license, version of macros * Use WebSocketEvent derive instead of impl WebSocketEvent for .. (#491) use derive macro instead of manual impl blocks * Move Shared<T> to types/mod.rs, bump some dependencies (#492) * deps: bump rustls to 0.21.11 This is done to fix CVE-2024-32650, which practically shouldn't affect us but it's still better not to use vulnerable dependencies. * deps: bump h2 to 0.3.26 This is done to fix another vulnerability, which should also not affect us (non-critical, in h2 servers) * fix: move Shared<T> to types/mod.rs * Reuse gateway backends, don't duplicate them for voice gateway (#493) * Refactor / fix login and register (#495) Change login and register to only use one ChorusUser object, change the api of related methods which were also somewhat ugly * Add the repository field to Cargo.toml * Ci improvements (#498) * bump wasm-bindgen version to 0.2.92 * change wasm-gecko to using ubuntu-latest, since geckodriver is not supported on macos-latest * check some common non-default feature configurations * add experimental semver checks * Update poem dependency * Convert timestamp fields to DateTime's * Feature lock different types for UserSettings::status * Make config register_configuration use Rights bitflag object * Update tests to use DateTime's for timestamps * Fix tests * Allow joined_at to default if field is not in responses. * Allow last_pin_timestamp to default if field is not in responses. * Remove serde(with) for message timestamps * Fix some iso timestamps being strings, not DateTime<Utc> (#499) * fix: some iso timestamps being strings * fix: register uses dates, not datetimes * Add sqlx::FromRow derive to GuildMember * remove dep: prefix in backend feature list * Implement sqlx Encode, Decode, Type for Rights bitflag object. * Use Snowflake in Claims * Use ChannelType enum on ChannelModifySchema * Feature lock Shared, so backend feature gets a facade type * Remove erroneous serde with attributes * Add From<Vec<GuildFeatures>> impl for GuildFeaturesList * Add feature sqlx locks for user, roles on GuildMember * Use distinct type for explicit_content_filter * Remove unused imports * Revert |
||
---|---|---|
.cargo | ||
.github/workflows | ||
chorus-macros | ||
examples | ||
src | ||
tests | ||
.gitignore | ||
.rusty-hook.toml | ||
CONTRIBUTING.md | ||
Cargo.lock | ||
Cargo.toml | ||
LICENSE | ||
README.md | ||
SECURITY.md | ||
build-wasm.sh | ||
semver_release_checks.yml | ||
test-wasm.sh |
README.md
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.16.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;
#[tokio::main]
async fn main() {
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
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.
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.
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.70.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.70.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
This crate uses Semantic Versioning 2.0.0 as its versioning scheme. You can read the specification here.
Contributing
See CONTRIBUTING.md.