Update README.md
This commit is contained in:
parent
05b9f1c801
commit
72c5d13eaf
88
README.md
88
README.md
|
@ -28,14 +28,15 @@
|
||||||
|
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
Chorus is a Rust library which poses as an API wrapper for [Spacebar Chat](https://github.com/spacebarchat/)
|
Chorus is a Rust library which poses as an API wrapper for [Spacebar Chat](https://github.com/spacebarchat/),
|
||||||
and Discord. It is designed to be easy to use, and to be compatible with both Discord and 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.
|
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
|
## A Tour of Chorus
|
||||||
|
|
||||||
Chorus combines all the required functionalities of a user-centric Spacebar library into one package.
|
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
|
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,
|
a WebSocket connection to the Gateway. This means that you can focus on building your application,
|
||||||
instead of worrying about the underlying implementation details.
|
instead of worrying about the underlying implementation details.
|
||||||
|
@ -44,12 +45,12 @@ To get started with Chorus, import it into your project by adding the following
|
||||||
|
|
||||||
```toml
|
```toml
|
||||||
[dependencies]
|
[dependencies]
|
||||||
chorus = "0.15.0"
|
chorus = "0.16.0"
|
||||||
```
|
```
|
||||||
|
|
||||||
### Establishing a Connection
|
### Establishing a Connection
|
||||||
|
|
||||||
To connect to a Spacebar compatible server, you need to create an [`Instance`](https://docs.rs/chorus/latest/chorus/instance/struct.Instance.html) like this:
|
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:
|
||||||
|
|
||||||
```rs
|
```rs
|
||||||
use chorus::instance::Instance;
|
use chorus::instance::Instance;
|
||||||
|
@ -81,7 +82,7 @@ let login_schema = LoginSchema {
|
||||||
password: "Correct-Horse-Battery-Staple".to_string(),
|
password: "Correct-Horse-Battery-Staple".to_string(),
|
||||||
..Default::default()
|
..Default::default()
|
||||||
};
|
};
|
||||||
// Each user connects to the Gateway. The Gateway connection lives on a separate thread. Depending on
|
// 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.
|
// the runtime feature you choose, this can potentially take advantage of all of your computers' threads.
|
||||||
let user = instance
|
let user = instance
|
||||||
.login_account(login_schema)
|
.login_account(login_schema)
|
||||||
|
@ -148,80 +149,6 @@ This crate uses Semantic Versioning 2.0.0 as its versioning scheme. You can read
|
||||||
|
|
||||||
See [CONTRIBUTING.md](./CONTRIBUTING.md).
|
See [CONTRIBUTING.md](./CONTRIBUTING.md).
|
||||||
|
|
||||||
<details>
|
|
||||||
<summary>Progress Tracker/Roadmap</summary>
|
|
||||||
|
|
||||||
### Core Functionality
|
|
||||||
- [x] Rate Limiter (hint: couldn't be fully tested due to [an Issue with the Spacebar Server](https://github.com/spacebarchat/server/issues/1022))
|
|
||||||
- [x] [Login (the conventional way)](https://github.com/polyphony-chat/chorus/issues/1)
|
|
||||||
- [ ] [2FA](https://github.com/polyphony-chat/chorus/issues/40)
|
|
||||||
- [x] [Registration](https://github.com/polyphony-chat/chorus/issues/1)
|
|
||||||
|
|
||||||
### Messaging
|
|
||||||
- [x] [Sending messages](https://github.com/polyphony-chat/chorus/issues/23)
|
|
||||||
- [x] [Events (Message, User, Channel, etc.)](https://github.com/polyphony-chat/chorus/issues/51)
|
|
||||||
- [x] Channel creation
|
|
||||||
- [x] Channel deletion
|
|
||||||
- [x] [Channel management (name, description, icon, etc.)](https://github.com/polyphony-chat/chorus/issues/48)
|
|
||||||
- [x] [Join and Leave Guilds](https://github.com/polyphony-chat/chorus/issues/45)
|
|
||||||
- [x] [Start DMs](https://github.com/polyphony-chat/chorus/issues/45)
|
|
||||||
- [x] [Group DM creation, deletion and member management](https://github.com/polyphony-chat/chorus/issues/89)
|
|
||||||
- [ ] [Deleting messages](https://github.com/polyphony-chat/chorus/issues/91)
|
|
||||||
- [ ] [Message threads](https://github.com/polyphony-chat/chorus/issues/90)
|
|
||||||
- [x] [Reactions](https://github.com/polyphony-chat/chorus/issues/85)
|
|
||||||
- [ ] Message Search
|
|
||||||
- [ ] Message history
|
|
||||||
- [ ] Emoji
|
|
||||||
- [ ] Stickers
|
|
||||||
- [ ] [Forum channels](https://github.com/polyphony-chat/chorus/issues/90)
|
|
||||||
|
|
||||||
### User Management
|
|
||||||
- [ ] [User profile customization](https://github.com/polyphony-chat/chorus/issues/41)
|
|
||||||
- [x] Gettings users and user profiles
|
|
||||||
- [x] [Friend requests](https://github.com/polyphony-chat/chorus/issues/92)
|
|
||||||
- [x] [Blocking users](https://github.com/polyphony-chat/chorus/issues/92)
|
|
||||||
- [ ] User presence (online, offline, idle, etc.)
|
|
||||||
- [ ] User status (custom status, etc.)
|
|
||||||
- [x] Account deletion
|
|
||||||
|
|
||||||
### Additional Features
|
|
||||||
- [ ] Server discovery
|
|
||||||
- [ ] Server templates
|
|
||||||
|
|
||||||
### Voice and Video
|
|
||||||
- [ ] [Voice chat support](https://github.com/polyphony-chat/chorus/issues/49)
|
|
||||||
- [ ] [Video chat support](https://github.com/polyphony-chat/chorus/issues/49)
|
|
||||||
|
|
||||||
### Permissions and Roles
|
|
||||||
- [x] [Role management](https://github.com/polyphony-chat/chorus/issues/46) (creation, deletion, modification)
|
|
||||||
- [x] [Permission management](https://github.com/polyphony-chat/chorus/issues/46) (assigning and revoking permissions)
|
|
||||||
- [x] [Channel-specific permissions](https://github.com/polyphony-chat/chorus/issues/88)
|
|
||||||
- [x] Role-based access control
|
|
||||||
|
|
||||||
### Guild Management
|
|
||||||
- [x] Guild creation
|
|
||||||
- [x] Guild deletion
|
|
||||||
- [ ] [Guild settings (name, description, icon, etc.)](https://github.com/polyphony-chat/chorus/issues/43)
|
|
||||||
- [ ] Guild invites
|
|
||||||
|
|
||||||
### Moderation
|
|
||||||
- [ ] Channel moderation (slow mode, etc.)
|
|
||||||
- [ ] User sanctions (mute, kick, ban)
|
|
||||||
- [ ] Audit logs
|
|
||||||
|
|
||||||
### Embeds and Rich Content
|
|
||||||
- [x] Sending rich content in messages (links, images, videos)
|
|
||||||
- [ ] Customizing embed appearance (title, description, color, fields)
|
|
||||||
|
|
||||||
### Webhooks
|
|
||||||
- [ ] Webhook creation and management
|
|
||||||
- [ ] Handling incoming webhook events
|
|
||||||
|
|
||||||
### Documentation and Examples
|
|
||||||
- [ ] Comprehensive documentation
|
|
||||||
- [ ] Example usage and code snippets
|
|
||||||
- [ ] Tutorials and guides
|
|
||||||
|
|
||||||
[Rust]: https://img.shields.io/badge/Rust-orange?style=plastic&logo=rust
|
[Rust]: https://img.shields.io/badge/Rust-orange?style=plastic&logo=rust
|
||||||
[Rust-url]: https://www.rust-lang.org/
|
[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-shield]: https://img.shields.io/github/actions/workflow/status/polyphony-chat/chorus/build_and_test.yml?style=flat
|
||||||
|
@ -242,4 +169,3 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md).
|
||||||
[license-url]: https://github.com/polyphony-chat/chorus/blob/master/LICENSE
|
[license-url]: https://github.com/polyphony-chat/chorus/blob/master/LICENSE
|
||||||
[Discord]: https://dcbadge.vercel.app/api/server/m3FpcapGDD?style=flat
|
[Discord]: https://dcbadge.vercel.app/api/server/m3FpcapGDD?style=flat
|
||||||
[Discord-invite]: https://discord.com/invite/m3FpcapGDD
|
[Discord-invite]: https://discord.com/invite/m3FpcapGDD
|
||||||
</details>
|
|
||||||
|
|
54
src/lib.rs
54
src/lib.rs
|
@ -3,27 +3,29 @@
|
||||||
// file, You can obtain one at http://mozilla.org/MPL/2.0/.
|
// file, You can obtain one at http://mozilla.org/MPL/2.0/.
|
||||||
|
|
||||||
/*!
|
/*!
|
||||||
Chorus combines all the required functionalities of a user-centric Spacebar library into one package.
|
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.
|
||||||
|
|
||||||
|
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
|
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,
|
a WebSocket connection to the Gateway. This means that you can focus on building your application,
|
||||||
instead of worrying about the underlying implementation details.
|
instead of worrying about the underlying implementation details.
|
||||||
|
|
||||||
### Establishing a Connection
|
### Establishing a Connection
|
||||||
|
|
||||||
To connect to a Spacebar compatible server, you need to create an [`Instance`](https://docs.rs/chorus/latest/chorus/instance/struct.Instance.html) like this:
|
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:
|
||||||
|
|
||||||
```rs
|
```rs
|
||||||
use chorus::instance::Instance;
|
use chorus::instance::Instance;
|
||||||
use chorus::UrlBundle;
|
|
||||||
|
|
||||||
#[tokio::main]
|
#[tokio::main]
|
||||||
async fn main() {
|
async fn main() {
|
||||||
let bundle = UrlBundle::new(
|
let instance = Instance::new("https://example.com")
|
||||||
"https://example.com/api".to_string(),
|
|
||||||
"wss://example.com/".to_string(),
|
|
||||||
"https://example.com/cdn".to_string(),
|
|
||||||
);
|
|
||||||
let instance = Instance::new(bundle)
|
|
||||||
.await
|
.await
|
||||||
.expect("Failed to connect to the Spacebar server");
|
.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.
|
// You can create as many instances of `Instance` as you want, but each `Instance` should likely be unique.
|
||||||
|
@ -36,7 +38,7 @@ This Instance can now be used to log in, register and from there on, interact wi
|
||||||
|
|
||||||
### Logging In
|
### Logging In
|
||||||
|
|
||||||
Logging in correctly provides you with an instance of [`ChorusUser`](https://docs.rs/chorus/latest/chorus/instance/struct.ChorusUser.html), with which you can interact with the server and
|
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:
|
manipulate the account. Assuming you already have an account on the server, you can log in like this:
|
||||||
|
|
||||||
```rs
|
```rs
|
||||||
|
@ -48,7 +50,7 @@ let login_schema = LoginSchema {
|
||||||
password: "Correct-Horse-Battery-Staple".to_string(),
|
password: "Correct-Horse-Battery-Staple".to_string(),
|
||||||
..Default::default()
|
..Default::default()
|
||||||
};
|
};
|
||||||
// Each user connects to the Gateway. The Gateway connection lives on a separate thread. Depending on
|
// 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.
|
// the runtime feature you choose, this can potentially take advantage of all of your computers' threads.
|
||||||
let user = instance
|
let user = instance
|
||||||
.login_account(login_schema)
|
.login_account(login_schema)
|
||||||
|
@ -64,15 +66,33 @@ All major desktop operating systems (Windows, macOS (aarch64/x86_64), Linux (aar
|
||||||
`wasm32-unknown-unknown` is a supported compilation target on versions `0.12.0` and up. This allows you to use
|
`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.
|
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.
|
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.
|
||||||
|
|
||||||
## MSRV (Minimum Supported Rust Version)
|
## 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.
|
Rust **1.70.0**. This number might change at any point while Chorus is not yet at version 1.0.0.
|
||||||
|
|
||||||
## Development Setup
|
## Development Setup
|
||||||
|
|
||||||
Make sure that you have at least Rust 1.67.1 installed. You can check your Rust version by running `cargo --version`
|
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.
|
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`.
|
You can do this by running `rustup target add wasm32-unknown-unknown`.
|
||||||
|
|
||||||
|
@ -86,12 +106,16 @@ like "proxy connection checking" are already disabled on this version, which oth
|
||||||
### wasm
|
### wasm
|
||||||
|
|
||||||
To test for wasm, you will need to `cargo install wasm-pack`. You can then run
|
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" --no-default-features`
|
`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.
|
to run the tests for wasm.
|
||||||
|
|
||||||
## Versioning
|
## 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).
|
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).
|
||||||
|
|
||||||
|
## Contributing
|
||||||
|
|
||||||
|
See [CONTRIBUTING.md](./CONTRIBUTING.md).
|
||||||
!*/
|
!*/
|
||||||
#![doc(
|
#![doc(
|
||||||
html_logo_url = "https://raw.githubusercontent.com/polyphony-chat/design/main/branding/polyphony-chorus-round-8bit.png"
|
html_logo_url = "https://raw.githubusercontent.com/polyphony-chat/design/main/branding/polyphony-chorus-round-8bit.png"
|
||||||
|
|
Loading…
Reference in New Issue