2023-04-15 18:33:17 +02:00
< div align = "center" >
2023-04-10 21:28:22 +02:00
2023-05-25 18:33:17 +02:00
[![Discord]][Discord-invite]
2023-04-10 21:37:27 +02:00
[![Build][build-shield]][build-url]
2023-08-25 20:58:46 +02:00
[![Coverage][coverage-shield]][coverage-url]
2023-08-27 13:21:45 +02:00
< img src = "https://img.shields.io/static/v1?label=Status&message=Alpha&color=blue" >
2023-04-10 21:31:40 +02:00
2023-04-15 18:33:17 +02:00
< / br >
< div align = "center" >
< a href = "https://github.com/polyphony-chat/chorus" >
2023-11-25 13:26:24 +01:00
< img src = "https://github.com/polyphony-chat/branding/blob/main/logos/polyphony-chorus-round-8bit.png?raw=true" alt = "The chorus logo. a dark, square background with rounded edges. on this background, there are three vertically stacked, purple lines. The lines each resemble a sine curve." width = "128" height = "128" >
2023-04-15 18:33:17 +02:00
< / a >
< h3 align = "center" > Chorus< / h3 >
< p align = "center" >
< br / >
2023-11-24 21:37:30 +01:00
< a href = "https://docs.rs/chorus/latest/chorus/" > < strong > Explore the docs »< / strong > < / a >
2023-04-15 18:33:17 +02:00
< br / >
< br / >
< a href = "https://github.com/polyphony-chat/chorus/issues" > Report Bug< / a >
·
2023-11-24 21:37:30 +01:00
< a href = "https://crates.io/crates/chorus" > crates.io< / a >
2023-04-26 11:19:04 +02:00
·
< a href = "https://discord.gg/8tKSC8wzDq" > Join Discord< / a >
2023-04-15 18:33:17 +02:00
< / p >
< / div >
< / div >
2023-04-10 21:28:22 +02:00
2024-08-26 13:56:11 +02:00
Chorus is a Rust library which poses as an API wrapper for [Spacebar Chat ](https://github.com/spacebarchat/ ),
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.
2023-11-24 21:37:30 +01:00
You can establish as many connections to as many servers as you want, and you can use them all at the same time.
2023-06-20 00:17:52 +02:00
2023-11-13 22:20:57 +01:00
## A Tour of Chorus
2024-08-26 13:56:11 +02:00
Chorus combines all the required functionalities of an API wrapper for chat services into one modular library.
2023-11-24 21:37:30 +01:00
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.
2023-11-13 22:20:57 +01:00
To get started with Chorus, import it into your project by adding the following to your `Cargo.toml` file:
```toml
[dependencies]
2024-08-26 13:56:11 +02:00
chorus = "0.16.0"
2023-11-13 22:20:57 +01:00
```
### Establishing a Connection
2024-08-26 13:56:11 +02:00
To connect to a Polyphony/Spacebar compatible server, you'll need to create an [`Instance` ](https://docs.rs/chorus/latest/chorus/instance/struct.Instance.html ) like this:
2023-11-13 22:20:57 +01:00
```rs
use chorus::instance::Instance;
#[tokio::main]
async fn main() {
2024-08-26 19:36:42 +02:00
let instance = Instance::new("https://example.com", None)
2023-11-13 22:20:57 +01:00
.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:
```rs
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()
};
2024-08-26 13:56:11 +02:00
// Each user connects to the Gateway. Each users' Gateway connection lives on a separate thread. Depending on
2023-11-13 22:20:57 +01:00
// 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.
2023-11-22 16:14:33 +01:00
`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.
2023-11-13 22:20:57 +01:00
2024-07-13 08:31:45 +02:00
To compile for `wasm32-unknown-unknown` , execute the following command:
```sh
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.
2023-11-13 22:20:57 +01:00
## MSRV (Minimum Supported Rust Version)
2024-08-02 21:12:38 +02:00
Rust **1.70.0** . This number might change at any point while Chorus is not yet at version 1.0.0.
2023-11-13 22:20:57 +01:00
2023-11-22 14:20:45 +01:00
## Development Setup
2024-08-02 21:12:38 +02:00
Make sure that you have at least Rust 1.70.0 installed. You can check your Rust version by running `cargo --version`
2023-11-22 14:20:45 +01:00
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 ](https://docs.spacebar.chat/setup/server/ ). You can find a pre-configured version of the server
[here ](https://github.com/bitfl0wer/server ). 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
Primitive voice implementation (feature/voice) (#457)
* Add Webrtc Identify & Ready
* Add more webrtc typings
* Attempt an untested voice gateway implementation
* fmt
* Merge with main
* Same allow as for voice as normal gateway
* Test error observer
* Minor updates
* More derives
* Even more derives
* Small types update
* e
* Minor doc fixes
* Modernise voice gateway
* Add default impl for voicegatewayerror
* Make voice event fields pub
* Event updates via the scientific method
* ??
* Fix bad request in voice gateway init
* Voice gateway updates
* Fix error failing to 'deserialize' properly
* Update voice identify
* Clarify FIXME related to #430
* Update to v7
* Create seperate voice_gateway.rs and voice_udp.rs
* Restructure voice to new module
* fix: deserialization error in speaking bitflags
* feat: kinda janky ip discovery impl
* feat: return ip discovery data + minor update
* feat: packet parsing!
* fix: voice works again
* feat: add voice_media_sink_wants
(comitting uncommited changes to merge)
* chore: rename events/webrtc to events/voice_gateway
* Add UdpHandle
* chore: clippy + other misc updates
* fix: attempt to fix failing wasm build
* chore: yes clippy, that is indeed an unneeded return statement
* feat: add VoiceData struct
* feat: add VoiceData reference to UdpHandler
* feat: decryption?
* chore: formatting
* feat: add ssrc definition (op 12)
* feat: add untested sending & asbtract nonce generation
* feat: Public api! (sorta)
* small updates
* feat: add sequence number
* chore: yes
* feat: merge VoiceHandler into official development
* chore: yes clippy, you are special
* fix: duplicated gateway events
* feat: first try at vgw wasm compat
* fix: blunder
* fix: gateway connect using wrong url
* fix: properly using encrypted data, bad practice for buffer creation
* chore: split voice udp
* feat: udp error handling, create udp/backends
* fix: its the same
* chore: clarify UDP on WASM
* api: split voice gateway and udp features, test for voice gateway in WASM
* feat: new encryption modes, minor code quality
* docs: document voice encryption modes
* chore: unused imports
* chore: update getrandom version to match wasm version
* chore: update on packet size FIXME
* drop buf asap
* Okay can't do that actually
* tests: add nonce test
* normal tests work?
* docs: fix doc warning, fix incorrect refrences to 'webrtc'
* chore: json isn't a doc test
* tests: better gateway auth test
* testing tests
* update voice heartbeat, fix the new test issue
* committed too much
* fix: unused import
* fix: use ip discovery address as string, not as Vec<u8>
* chore: less obnoxious logging
* chore: better unimplemented voice modes handling
* chore: remove unused variable
* chore: use matches macro
* add voice examples, make gateway ones clearer
* rename voice example
* chore: remove unused VoiceHandler
* fix: implement gateway Reconnect and InvalidSession
* Typo
Co-authored-by: Flori <39242991+bitfl0wer@users.noreply.github.com>
* Fix a bunch of typos
Co-authored-by: Flori <39242991+bitfl0wer@users.noreply.github.com>
* fix: error handling while loading native certs
* fix: guh
* use be for nonce bytes
* fix: refactor gw and vgw closures
* remove outdated docs
---------
Co-authored-by: Flori <39242991+bitfl0wer@users.noreply.github.com>
2024-04-16 17:18:21 +02:00
`wasm-pack test --<chrome/firefox/safari> --headless -- --target wasm32-unknown-unknown --features="rt, client, voice_gateway" --no-default-features`
2023-11-22 14:20:45 +01:00
to run the tests for wasm.
2023-11-13 22:20:57 +01:00
## Versioning
This crate uses Semantic Versioning 2.0.0 as its versioning scheme. You can read the specification [here ](https://semver.org/spec/v2.0.0.html ).
2023-06-20 00:17:52 +02:00
## Contributing
2024-02-01 11:52:29 +01:00
See [CONTRIBUTING.md ](./CONTRIBUTING.md ).
2023-06-20 00:17:52 +02:00
2024-08-26 13:56:11 +02:00
[Rust]: https://img.shields.io/badge/Rust-orange?style=plastic& logo=rust
[Rust-url]: https://www.rust-lang.org/
[build-shield]: https://img.shields.io/github/actions/workflow/status/polyphony-chat/chorus/build_and_test.yml?style=flat
[build-url]: https://github.com/polyphony-chat/chorus/blob/main/.github/workflows/build_and_test.yml
[clippy-shield]: https://img.shields.io/github/actions/workflow/status/polyphony-chat/chorus/clippy.yml?style=flat
[clippy-url]: https://github.com/polyphony-chat/chorus/blob/main/.github/workflows/clippy.yml
[contributors-shield]: https://img.shields.io/github/contributors/polyphony-chat/chorus.svg?style=flat
[contributors-url]: https://github.com/polyphony-chat/chorus/graphs/contributors
[coverage-shield]: https://coveralls.io/repos/github/polyphony-chat/chorus/badge.svg?branch=main
[coverage-url]: https://coveralls.io/github/polyphony-chat/chorus?branch=main
[forks-shield]: https://img.shields.io/github/forks/polyphony-chat/chorus.svg?style=flat
[forks-url]: https://github.com/polyphony-chat/chorus/network/members
[stars-shield]: https://img.shields.io/github/stars/polyphony-chat/chorus.svg?style=flat
[stars-url]: https://github.com/polyphony-chat/chorus/stargazers
[issues-shield]: https://img.shields.io/github/issues/polyphony-chat/chorus.svg?style=flat
[issues-url]: https://github.com/polyphony-chat/chorus/issues
[license-shield]: https://img.shields.io/github/license/polyphony-chat/chorus.svg?style=f;at
[license-url]: https://github.com/polyphony-chat/chorus/blob/master/LICENSE
[Discord]: https://dcbadge.vercel.app/api/server/m3FpcapGDD?style=flat
[Discord-invite]: https://discord.com/invite/m3FpcapGDD