Enhancement/readme (#435)
This commit is contained in:
commit
12a58ada0d
92
README.md
92
README.md
|
@ -4,8 +4,6 @@
|
|||
[![Build][build-shield]][build-url]
|
||||
[![Coverage][coverage-shield]][coverage-url]
|
||||
[![Contributors][contributors-shield]][contributors-url]
|
||||
[![Forks][forks-shield]][forks-url]
|
||||
[![Issues][issues-shield]][issues-url]
|
||||
<img src="https://img.shields.io/static/v1?label=Status&message=Alpha&color=blue">
|
||||
|
||||
</br>
|
||||
|
@ -17,7 +15,6 @@
|
|||
<h3 align="center">Chorus</h3>
|
||||
|
||||
<p align="center">
|
||||
A rust library for interacting with (multiple) Spacebar-compatible APIs and Gateways (at the same time).
|
||||
<br />
|
||||
<a href="https://github.com/polyphony-chat/chorus"><strong>Explore the docs »</strong></a>
|
||||
<br />
|
||||
|
@ -32,16 +29,95 @@
|
|||
|
||||
</div>
|
||||
|
||||
## About
|
||||
Chorus is a Rust library that allows developers to interact with multiple Spacebar-compatible APIs and Gateways (Including
|
||||
Discord.com) simultaneously. The library provides a simple and efficient way to communicate with these services, making it easier for developers to build applications that rely on them. Chorus is open-source and welcomes contributions from the community.
|
||||
|
||||
Chorus is a Rust library that allows developers to interact with multiple Spacebar-compatible APIs and Gateways simultaneously. The library provides a simple and efficient way to communicate with these services, making it easier for developers to build applications that rely on them. Chorus is open-source and welcomes contributions from the community.
|
||||
## A Tour of Chorus
|
||||
|
||||
Chorus combines all the required functionalities of a user-centric Spacebar library into one package. The library
|
||||
handles a lot of things for you, such as rate limiting, authentication, and more. 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:
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
chorus = "0"
|
||||
```
|
||||
|
||||
### 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:
|
||||
|
||||
```rs
|
||||
use chorus::instance::Instance;
|
||||
use chorus::UrlBundle;
|
||||
|
||||
#[tokio::main]
|
||||
async fn main() {
|
||||
let bundle = UrlBundle::new(
|
||||
"https://example.com/api".to_string(),
|
||||
"wss://example.com/".to_string(),
|
||||
"https://example.com/cdn".to_string(),
|
||||
);
|
||||
let instance = Instance::new(bundle, true)
|
||||
.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()
|
||||
};
|
||||
// Each user connects to the Gateway. The Gateway connection lives on a seperate 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.
|
||||
We are currently working on adding full support for `wasm32-unknown-unknown`. This will allow you to use 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.
|
||||
|
||||
## 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.
|
||||
|
||||
## 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).
|
||||
|
||||
## Contributing
|
||||
|
||||
Chorus is currently missing voice support and a lot of API endpoints, many of which should be trivial to implement,
|
||||
ever since [we streamlined the process of doing so](https://github.com/polyphony-chat/chorus/discussions/401).
|
||||
|
||||
If you'd like to contribute new functionality, check out [The 'Meta'-issues.](https://github.com/polyphony-chat/chorus/issues?q=is%3Aissue+label%3A%22Type%3A+Meta%22+) They contain a comprehensive list of all features which are yet missing for full Discord.com compatibility.
|
||||
If you would like to contribute, please feel free to open an Issue with the idea you have, or a
|
||||
Pull Request. Please keep our [contribution guidelines](https://github.com/polyphony-chat/.github/blob/main/CONTRIBUTION_GUIDELINES.md) in mind. Your contribution might not be
|
||||
accepted, if it violates these guidelines or [our Code of Conduct](https://github.com/polyphony-chat/.github/blob/main/CODE_OF_CONDUCT.md).
|
||||
Please feel free to open an Issue with the idea you have, or a Pull Request. Please keep our [contribution guidelines](https://github.com/polyphony-chat/.github/blob/main/CONTRIBUTION_GUIDELINES.md) in mind. Your contribution might not be accepted if it violates these guidelines or [our Code of Conduct](https://github.com/polyphony-chat/.github/blob/main/CODE_OF_CONDUCT.md).
|
||||
|
||||
<details>
|
||||
<summary>Progress Tracker/Roadmap</summary>
|
||||
|
|
|
@ -0,0 +1,16 @@
|
|||
use chorus::instance::Instance;
|
||||
use chorus::UrlBundle;
|
||||
|
||||
#[tokio::main]
|
||||
async fn main() {
|
||||
let bundle = UrlBundle::new(
|
||||
"https://example.com/api".to_string(),
|
||||
"wss://example.com/".to_string(),
|
||||
"https://example.com/cdn".to_string(),
|
||||
);
|
||||
let instance = Instance::new(bundle, true)
|
||||
.await
|
||||
.expect("Failed to connect to the Spacebar server");
|
||||
dbg!(instance.instance_info);
|
||||
dbg!(instance.limits_information);
|
||||
}
|
|
@ -0,0 +1,30 @@
|
|||
use chorus::instance::Instance;
|
||||
use chorus::types::LoginSchema;
|
||||
use chorus::UrlBundle;
|
||||
|
||||
#[tokio::main]
|
||||
async fn main() {
|
||||
let bundle = UrlBundle::new(
|
||||
"https://example.com/api".to_string(),
|
||||
"wss://example.com/".to_string(),
|
||||
"https://example.com/cdn".to_string(),
|
||||
);
|
||||
let instance = Instance::new(bundle, true)
|
||||
.await
|
||||
.expect("Failed to connect to the Spacebar server");
|
||||
// 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. The Gateway connection lives on a seperate 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);
|
||||
}
|
Loading…
Reference in New Issue