@@ -37,6 +38,7 @@ Chorus is a Rust library that allows developers to interact with multiple Spaceb
## Contributing
+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).
@@ -123,6 +125,8 @@ accepted, if it violates these guidelines or [our Code of Conduct](https://githu
[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
@@ -133,4 +137,4 @@ accepted, if it violates these guidelines or [our Code of Conduct](https://githu
[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
-
\ No newline at end of file
+
diff --git a/chorus-macros/Cargo.lock b/chorus-macros/Cargo.lock
index 4aa96d3..17404a2 100644
--- a/chorus-macros/Cargo.lock
+++ b/chorus-macros/Cargo.lock
@@ -2,10 +2,22 @@
# It is not intended for manual editing.
version = 3
+[[package]]
+name = "async-trait"
+version = "0.1.73"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bc00ceb34980c03614e35a3a4e218276a0a824e911d07651cd0d858a51e8c0f0"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
[[package]]
name = "chorus-macros"
version = "0.1.0"
dependencies = [
+ "async-trait",
"quote",
"syn",
]
@@ -21,18 +33,18 @@ dependencies = [
[[package]]
name = "quote"
-version = "1.0.31"
+version = "1.0.33"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5fe8a65d69dd0808184ebb5f836ab526bb259db23c657efa38711b1072ee47f0"
+checksum = "5267fca4496028628a95160fc423a33e8b2e6af8a5302579e322e4b520293cae"
dependencies = [
"proc-macro2",
]
[[package]]
name = "syn"
-version = "2.0.27"
+version = "2.0.29"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b60f673f44a8255b9c8c657daf66a596d435f2da81a555b06dc644d080ba45e0"
+checksum = "c324c494eba9d92503e6f1ef2e6df781e78f6a7705a0202d9801b198807d518a"
dependencies = [
"proc-macro2",
"quote",
diff --git a/chorus-macros/Cargo.toml b/chorus-macros/Cargo.toml
index cffffe1..272d99f 100644
--- a/chorus-macros/Cargo.toml
+++ b/chorus-macros/Cargo.toml
@@ -1,11 +1,14 @@
[package]
name = "chorus-macros"
-version = "0.1.0"
+version = "0.2.0"
edition = "2021"
+license = "AGPL-3.0"
+description = "Macros for the chorus crate."
[lib]
proc-macro = true
[dependencies]
-quote = "1"
-syn = "2"
+quote = "1.0.33"
+syn = "2.0.29"
+async-trait = "0.1.73"
diff --git a/chorus-macros/src/lib.rs b/chorus-macros/src/lib.rs
index c8d5e87..fd68df0 100644
--- a/chorus-macros/src/lib.rs
+++ b/chorus-macros/src/lib.rs
@@ -1,5 +1,6 @@
use proc_macro::TokenStream;
use quote::quote;
+use syn::{parse_macro_input, Data, DeriveInput, Field, Fields, FieldsNamed};
#[proc_macro_derive(Updateable)]
pub fn updateable_macro_derive(input: TokenStream) -> TokenStream {
@@ -16,3 +17,125 @@ pub fn updateable_macro_derive(input: TokenStream) -> TokenStream {
}
.into()
}
+
+#[proc_macro_derive(JsonField)]
+pub fn jsonfield_macro_derive(input: TokenStream) -> TokenStream {
+ let ast: syn::DeriveInput = syn::parse(input).unwrap();
+
+ let name = &ast.ident;
+ // No need for macro hygiene, we're only using this in chorus
+ quote! {
+ impl JsonField for #name {
+ fn get_json(&self) -> String {
+ self.json.clone()
+ }
+ fn set_json(&mut self, json: String) {
+ self.json = json;
+ }
+ }
+ }
+ .into()
+}
+
+#[proc_macro_derive(SourceUrlField)]
+pub fn source_url_macro_derive(input: TokenStream) -> TokenStream {
+ let ast: syn::DeriveInput = syn::parse(input).unwrap();
+
+ let name = &ast.ident;
+ // No need for macro hygiene, we're only using this in chorus
+ quote! {
+ impl SourceUrlField for #name {
+ fn get_source_url(&self) -> String {
+ self.source_url.clone()
+ }
+ fn set_source_url(&mut self, url: String) {
+ self.source_url = url;
+ }
+ }
+ }
+ .into()
+}
+
+#[proc_macro_attribute]
+pub fn observe_option(_args: TokenStream, input: TokenStream) -> TokenStream {
+ input
+}
+
+#[proc_macro_attribute]
+pub fn observe_option_vec(_args: TokenStream, input: TokenStream) -> TokenStream {
+ input
+}
+
+#[proc_macro_attribute]
+pub fn observe(_args: TokenStream, input: TokenStream) -> TokenStream {
+ input
+}
+
+#[proc_macro_attribute]
+pub fn observe_vec(_args: TokenStream, input: TokenStream) -> TokenStream {
+ input
+}
+
+#[proc_macro_derive(
+ Composite,
+ attributes(observe_option_vec, observe_option, observe, observe_vec)
+)]
+pub fn composite_derive(input: TokenStream) -> TokenStream {
+ let input = parse_macro_input!(input as DeriveInput);
+
+ let process_field = |field: &Field| {
+ let field_name = &field.ident;
+ let attrs = &field.attrs;
+
+ let observe_option = attrs
+ .iter()
+ .any(|attr| attr.path().is_ident("observe_option"));
+ let observe_option_vec = attrs
+ .iter()
+ .any(|attr| attr.path().is_ident("observe_option_vec"));
+ let observe = attrs.iter().any(|attr| attr.path().is_ident("observe"));
+ let observe_vec = attrs.iter().any(|attr| attr.path().is_ident("observe_vec"));
+
+ match (observe_option, observe_option_vec, observe, observe_vec) {
+ (true, _, _, _) => quote! {
+ #field_name: Self::option_observe_fn(self.#field_name, gateway).await
+ },
+ (_, true, _, _) => quote! {
+ #field_name: Self::option_vec_observe_fn(self.#field_name, gateway).await
+ },
+ (_, _, true, _) => quote! {
+ #field_name: Self::value_observe_fn(self.#field_name, gateway).await
+ },
+ (_, _, _, true) => quote! {
+ #field_name: Self::vec_observe_fn(self.#field_name, gateway).await
+ },
+ _ => quote! {
+ #field_name: self.#field_name
+ },
+ }
+ };
+
+ match &input.data {
+ Data::Struct(data) => match &data.fields {
+ Fields::Named(FieldsNamed { named, .. }) => {
+ let field_exprs = named.iter().map(process_field);
+
+ let ident = &input.ident;
+ let expanded = quote! {
+ #[async_trait::async_trait(?Send)]
+ impl
Composite for #ident {
+ async fn watch_whole(self, gateway: &GatewayHandle) -> Self {
+ Self {
+ #(#field_exprs,)*
+ }
+ }
+ }
+ };
+
+ TokenStream::from(expanded)
+ }
+ _ => panic!("Composite derive macro only supports named fields"),
+ },
+ _ => panic!("Composite derive macro only supports structs"),
+ }
+}
diff --git a/src/api/auth/login.rs b/src/api/auth/login.rs
index 68604d9..272ee04 100644
--- a/src/api/auth/login.rs
+++ b/src/api/auth/login.rs
@@ -1,30 +1,33 @@
-use std::cell::RefCell;
-use std::rc::Rc;
+use std::sync::{Arc, RwLock};
use reqwest::Client;
use serde_json::to_string;
-use crate::api::LimitType;
use crate::errors::ChorusResult;
use crate::gateway::Gateway;
-use crate::instance::{Instance, UserMeta};
+use crate::instance::{ChorusUser, Instance};
use crate::ratelimiter::ChorusRequest;
-use crate::types::{GatewayIdentifyPayload, LoginResult, LoginSchema};
+use crate::types::{GatewayIdentifyPayload, LimitType, LoginResult, LoginSchema};
impl Instance {
- pub async fn login_account(&mut self, login_schema: &LoginSchema) -> ChorusResult {
+ /// Logs into an existing account on the spacebar server.
+ ///
+ /// # Reference
+ /// See
+ pub async fn login_account(mut self, login_schema: LoginSchema) -> ChorusResult {
let endpoint_url = self.urls.api.clone() + "/auth/login";
let chorus_request = ChorusRequest {
request: Client::new()
.post(endpoint_url)
- .body(to_string(login_schema).unwrap()),
+ .body(to_string(&login_schema).unwrap())
+ .header("Content-Type", "application/json"),
limit_type: LimitType::AuthLogin,
};
// We do not have a user yet, and the UserRateLimits will not be affected by a login
// request (since login is an instance wide limit), which is why we are just cloning the
// instances' limits to pass them on as user_rate_limits later.
let mut shell =
- UserMeta::shell(Rc::new(RefCell::new(self.clone())), "None".to_string()).await;
+ ChorusUser::shell(Arc::new(RwLock::new(self.clone())), "None".to_string()).await;
let login_result = chorus_request
.deserialize_response::(&mut shell)
.await?;
@@ -36,12 +39,12 @@ impl Instance {
let gateway = Gateway::new(self.urls.wss.clone()).await.unwrap();
identify.token = login_result.token.clone();
gateway.send_identify(identify).await;
- let user = UserMeta::new(
- Rc::new(RefCell::new(self.clone())),
+ let user = ChorusUser::new(
+ Arc::new(RwLock::new(self.clone())),
login_result.token,
self.clone_limits_if_some(),
login_result.settings,
- object,
+ Arc::new(RwLock::new(object)),
gateway,
);
Ok(user)
diff --git a/src/api/auth/mod.rs b/src/api/auth/mod.rs
index 663bf5e..3ad4a60 100644
--- a/src/api/auth/mod.rs
+++ b/src/api/auth/mod.rs
@@ -1,5 +1,41 @@
+use std::sync::{Arc, RwLock};
+
pub use login::*;
pub use register::*;
+use crate::{
+ errors::ChorusResult,
+ gateway::Gateway,
+ instance::{ChorusUser, Instance},
+ types::{GatewayIdentifyPayload, User},
+};
+
pub mod login;
pub mod register;
+
+impl Instance {
+ /// Logs into an existing account on the spacebar server, using only a token.
+ pub async fn login_with_token(&mut self, token: String) -> ChorusResult {
+ let object_result = self.get_user(token.clone(), None).await;
+ if let Err(e) = object_result {
+ return Result::Err(e);
+ }
+
+ let user_settings = User::get_settings(&token, &self.urls.api, &mut self.clone())
+ .await
+ .unwrap();
+ let mut identify = GatewayIdentifyPayload::common();
+ let gateway = Gateway::new(self.urls.wss.clone()).await.unwrap();
+ identify.token = token.clone();
+ gateway.send_identify(identify).await;
+ let user = ChorusUser::new(
+ Arc::new(RwLock::new(self.clone())),
+ token.clone(),
+ self.clone_limits_if_some(),
+ Arc::new(RwLock::new(user_settings)),
+ Arc::new(RwLock::new(object_result.unwrap())),
+ gateway,
+ );
+ Ok(user)
+ }
+}
diff --git a/src/api/auth/register.rs b/src/api/auth/register.rs
index e818d82..d10915e 100644
--- a/src/api/auth/register.rs
+++ b/src/api/auth/register.rs
@@ -1,4 +1,4 @@
-use std::{cell::RefCell, rc::Rc};
+use std::sync::{Arc, RwLock};
use reqwest::Client;
use serde_json::to_string;
@@ -6,39 +6,35 @@ use serde_json::to_string;
use crate::gateway::Gateway;
use crate::types::GatewayIdentifyPayload;
use crate::{
- api::policies::instance::LimitType,
errors::ChorusResult,
- instance::{Instance, Token, UserMeta},
+ instance::{ChorusUser, Instance, Token},
ratelimiter::ChorusRequest,
+ types::LimitType,
types::RegisterSchema,
};
impl Instance {
- /// Registers a new user on the Spacebar server.
+ /// Registers a new user on the server.
///
- /// # Arguments
- ///
- /// * `register_schema` - The [`RegisterSchema`] that contains all the information that is needed to register a new user.
- ///
- /// # Errors
- ///
- /// * [`ChorusLibError`] - If the server does not respond.
+ /// # Reference
+ /// See
pub async fn register_account(
- &mut self,
- register_schema: &RegisterSchema,
- ) -> ChorusResult {
+ mut self,
+ register_schema: RegisterSchema,
+ ) -> ChorusResult {
let endpoint_url = self.urls.api.clone() + "/auth/register";
let chorus_request = ChorusRequest {
request: Client::new()
.post(endpoint_url)
- .body(to_string(register_schema).unwrap()),
+ .body(to_string(®ister_schema).unwrap())
+ .header("Content-Type", "application/json"),
limit_type: LimitType::AuthRegister,
};
// We do not have a user yet, and the UserRateLimits will not be affected by a login
// request (since register is an instance wide limit), which is why we are just cloning
// the instances' limits to pass them on as user_rate_limits later.
let mut shell =
- UserMeta::shell(Rc::new(RefCell::new(self.clone())), "None".to_string()).await;
+ ChorusUser::shell(Arc::new(RwLock::new(self.clone())), "None".to_string()).await;
let token = chorus_request
.deserialize_response::(&mut shell)
.await?
@@ -47,17 +43,17 @@ impl Instance {
self.limits_information.as_mut().unwrap().ratelimits = shell.limits.unwrap();
}
let user_object = self.get_user(token.clone(), None).await.unwrap();
- let settings = UserMeta::get_settings(&token, &self.urls.api.clone(), self).await?;
+ let settings = ChorusUser::get_settings(&token, &self.urls.api.clone(), &mut self).await?;
let mut identify = GatewayIdentifyPayload::common();
let gateway = Gateway::new(self.urls.wss.clone()).await.unwrap();
identify.token = token.clone();
gateway.send_identify(identify).await;
- let user = UserMeta::new(
- Rc::new(RefCell::new(self.clone())),
+ let user = ChorusUser::new(
+ Arc::new(RwLock::new(self.clone())),
token.clone(),
self.clone_limits_if_some(),
- settings,
- user_object,
+ Arc::new(RwLock::new(settings)),
+ Arc::new(RwLock::new(user_object)),
gateway,
);
Ok(user)
diff --git a/src/api/channels/channels.rs b/src/api/channels/channels.rs
index df8e290..9560d74 100644
--- a/src/api/channels/channels.rs
+++ b/src/api/channels/channels.rs
@@ -1,126 +1,165 @@
use reqwest::Client;
use serde_json::to_string;
-use crate::types::AddChannelRecipientSchema;
+use crate::types::{AddChannelRecipientSchema, ModifyChannelPositionsSchema};
use crate::{
- api::LimitType,
errors::{ChorusError, ChorusResult},
- instance::UserMeta,
+ instance::ChorusUser,
ratelimiter::ChorusRequest,
- types::{Channel, ChannelModifySchema, GetChannelMessagesSchema, Message, Snowflake},
+ types::{
+ Channel, ChannelModifySchema, GetChannelMessagesSchema, LimitType, Message, Snowflake,
+ },
};
impl Channel {
- pub async fn get(user: &mut UserMeta, channel_id: Snowflake) -> ChorusResult {
- let url = user.belongs_to.borrow().urls.api.clone();
- let chorus_request = ChorusRequest {
- request: Client::new()
- .get(format!("{}/channels/{}/", url, channel_id))
- .bearer_auth(user.token()),
- limit_type: LimitType::Channel(channel_id),
- };
+ /// Retrieves a channel from the server.
+ ///
+ /// # Reference
+ /// See
+ pub async fn get(user: &mut ChorusUser, channel_id: Snowflake) -> ChorusResult {
+ let chorus_request = ChorusRequest::new(
+ http::Method::GET,
+ &format!(
+ "{}/channels/{}",
+ user.belongs_to.read().unwrap().urls.api.clone(),
+ channel_id
+ ),
+ None,
+ None,
+ None,
+ Some(user),
+ LimitType::Channel(channel_id),
+ );
+
chorus_request.deserialize_response::(user).await
}
- /// Deletes a channel.
+ /// Deletes self.
///
- /// # Arguments
+ /// Requires the [`MANAGE_CHANNELS`](crate::types::PermissionFlags::MANAGE_CHANNELS) permission in a guild, or
+ /// the [`MANAGE_THREADS`](crate::types::PermissionFlags::MANAGE_THREADS) permission if the channel is a thread.
///
- /// * `token` - A string slice that holds the authorization token.
- /// * `url_api` - A string slice that holds the URL of the API.
- /// * `channel` - A `Channel` object that represents the channel to be deleted.
- /// * `limits_user` - A mutable reference to a `Limits` object that represents the user's rate limits.
- /// * `limits_instance` - A mutable reference to a `Limits` object that represents the instance's rate limits.
- ///
- /// # Returns
- ///
- /// A `Result` that contains a `ChorusLibError` if an error occurred during the request, or `()` if the request was successful.
- pub async fn delete(self, user: &mut UserMeta) -> ChorusResult<()> {
- let chorus_request = ChorusRequest {
- request: Client::new()
- .delete(format!(
- "{}/channels/{}/",
- user.belongs_to.borrow().urls.api,
- self.id
- ))
- .bearer_auth(user.token()),
- limit_type: LimitType::Channel(self.id),
- };
- chorus_request.handle_request_as_result(user).await
+ /// # Reference
+ /// See
+ pub async fn delete(
+ self,
+ audit_log_reason: Option,
+ user: &mut ChorusUser,
+ ) -> ChorusResult<()> {
+ let url = format!(
+ "{}/channels/{}",
+ user.belongs_to.read().unwrap().urls.api,
+ self.id,
+ );
+
+ let request = ChorusRequest::new(
+ http::Method::DELETE,
+ &url,
+ None,
+ audit_log_reason.as_deref(),
+ None,
+ Some(user),
+ LimitType::Channel(self.id),
+ );
+
+ request.handle_request_as_result(user).await
}
- /// Modifies a channel.
+ /// Modifies a channel with the provided data.
+ /// Returns the new Channel.
///
- /// # Arguments
+ /// Requires the [`MANAGE_CHANNELS`](crate::types::PermissionFlags::MANAGE_CHANNELS) permission in a guild.
///
- /// * `modify_data` - A `ChannelModifySchema` object that represents the modifications to be made to the channel.
- /// * `token` - A string slice that holds the authorization token.
- /// * `url_api` - A string slice that holds the URL of the API.
- /// * `channel_id` - A string slice that holds the ID of the channel to be modified.
- /// * `limits_user` - A mutable reference to a `Limits` object that represents the user's rate limits.
- /// * `limits_instance` - A mutable reference to a `Limits` object that represents the instance's rate limits.
+ /// If modifying permission overwrites, the [`MANAGE_ROLES`](crate::types::PermissionFlags::MANAGE_ROLES) permission is required.
+ /// Only permissions you have in the guild or parent channel (if applicable) can be allowed/denied
+ /// (unless you have a [`MANAGE_ROLES`](crate::types::PermissionFlags::MANAGE_ROLES) overwrite in the channel).
///
- /// # Returns
+ /// If modifying a thread and setting `archived` to `false`, when `locked` is also `false`, only the [`SEND_MESSAGES`](crate::types::PermissionFlags::SEND_MESSAGES) permission is required.
+ /// Otherwise, requires the [`MANAGE_THREADS`](crate::types::PermissionFlags::MANAGE_THREADS) permission. Requires the thread to have `archived` set to `false` or be set to `false` in the request.
///
- /// A `Result` that contains a `Channel` object if the request was successful, or an `ChorusLibError` if an error occurred during the request.
+ /// # Reference
+ /// See
pub async fn modify(
&self,
modify_data: ChannelModifySchema,
- channel_id: Snowflake,
- user: &mut UserMeta,
+ audit_log_reason: Option,
+ user: &mut ChorusUser,
) -> ChorusResult {
- let chorus_request = ChorusRequest {
- request: Client::new()
- .patch(format!(
- "{}/channels/{}/",
- user.belongs_to.borrow().urls.api,
- channel_id
- ))
- .bearer_auth(user.token())
- .body(to_string(&modify_data).unwrap()),
- limit_type: LimitType::Channel(channel_id),
- };
- chorus_request.deserialize_response::(user).await
+ let channel_id = self.id;
+ let url = format!(
+ "{}/channels/{}",
+ user.belongs_to.read().unwrap().urls.api,
+ channel_id
+ );
+
+ let request = ChorusRequest::new(
+ http::Method::PATCH,
+ &url,
+ Some(to_string(&modify_data).unwrap()),
+ audit_log_reason.as_deref(),
+ None,
+ Some(user),
+ LimitType::Channel(channel_id),
+ );
+
+ request.deserialize_response::(user).await
}
+ /// Fetches recent messages from a channel.
+ ///
+ /// If operating on a guild channel, this endpoint requires the [`VIEW_CHANNEL`](crate::types::PermissionFlags::VIEW_CHANNEL) permission.
+ ///
+ /// If the user is missing the [`READ_MESSAGE_HISTORY`](crate::types::PermissionFlags::READ_MESSAGE_HISTORY) permission,
+ /// this method returns an empty list.
+ ///
+ /// # Reference
+ /// See
pub async fn messages(
range: GetChannelMessagesSchema,
channel_id: Snowflake,
- user: &mut UserMeta,
+ user: &mut ChorusUser,
) -> Result, ChorusError> {
- let chorus_request = ChorusRequest {
- request: Client::new()
- .get(format!(
- "{}/channels/{}/messages",
- user.belongs_to.borrow().urls.api,
- channel_id
- ))
- .bearer_auth(user.token())
- .query(&range),
- limit_type: Default::default(),
- };
+ let url = format!(
+ "{}/channels/{}/messages",
+ user.belongs_to.read().unwrap().urls.api,
+ channel_id
+ );
+
+ let mut chorus_request = ChorusRequest::new(
+ http::Method::GET,
+ &url,
+ None,
+ None,
+ None,
+ Some(user),
+ Default::default(),
+ );
+ chorus_request.request = chorus_request.request.query(&range);
chorus_request
.deserialize_response::>(user)
.await
}
+ /// Adds a recipient to a group DM.
+ ///
/// # Reference:
- /// Read:
+ /// See
pub async fn add_channel_recipient(
&self,
recipient_id: Snowflake,
- user: &mut UserMeta,
+ user: &mut ChorusUser,
add_channel_recipient_schema: Option,
) -> ChorusResult<()> {
let mut request = Client::new()
.put(format!(
- "{}/channels/{}/recipients/{}/",
- user.belongs_to.borrow().urls.api,
+ "{}/channels/{}/recipients/{}",
+ user.belongs_to.read().unwrap().urls.api,
self.id,
recipient_id
))
- .bearer_auth(user.token());
+ .header("Authorization", user.token())
+ .header("Content-Type", "application/json");
if let Some(schema) = add_channel_recipient_schema {
request = request.body(to_string(&schema).unwrap());
}
@@ -132,26 +171,61 @@ impl Channel {
.await
}
+ /// Removes a recipient from a group DM.
+ ///
/// # Reference:
- /// Read:
+ /// See
pub async fn remove_channel_recipient(
&self,
recipient_id: Snowflake,
- user: &mut UserMeta,
+ user: &mut ChorusUser,
) -> ChorusResult<()> {
- let request = Client::new()
- .delete(format!(
- "{}/channels/{}/recipients/{}/",
- user.belongs_to.borrow().urls.api,
- self.id,
- recipient_id
- ))
- .bearer_auth(user.token());
- ChorusRequest {
- request,
- limit_type: LimitType::Channel(self.id),
- }
- .handle_request_as_result(user)
- .await
+ let url = format!(
+ "{}/channels/{}/recipients/{}",
+ user.belongs_to.read().unwrap().urls.api,
+ self.id,
+ recipient_id
+ );
+
+ let request = ChorusRequest::new(
+ http::Method::DELETE,
+ &url,
+ None,
+ None,
+ None,
+ Some(user),
+ LimitType::Channel(self.id),
+ );
+
+ request.handle_request_as_result(user).await
+ }
+
+ /// Modifies the positions of a set of channel objects for the guild. Requires the `MANAGE_CHANNELS` permission.
+ /// Only channels to be modified are required.
+ ///
+ /// # Reference:
+ /// See
+ pub async fn modify_positions(
+ schema: Vec,
+ guild_id: Snowflake,
+ user: &mut ChorusUser,
+ ) -> ChorusResult<()> {
+ let url = format!(
+ "{}/guilds/{}/channels",
+ user.belongs_to.read().unwrap().urls.api,
+ guild_id
+ );
+
+ let request = ChorusRequest::new(
+ http::Method::PATCH,
+ &url,
+ Some(to_string(&schema).unwrap()),
+ None,
+ None,
+ Some(user),
+ LimitType::Guild(guild_id),
+ );
+
+ request.handle_request_as_result(user).await
}
}
diff --git a/src/api/channels/messages.rs b/src/api/channels/messages.rs
index 6beec7f..6dfdfbf 100644
--- a/src/api/channels/messages.rs
+++ b/src/api/channels/messages.rs
@@ -1,27 +1,36 @@
use http::header::CONTENT_DISPOSITION;
use http::HeaderMap;
use reqwest::{multipart, Client};
-use serde_json::to_string;
+use serde_json::{from_value, to_string, Value};
-use crate::api::LimitType;
-use crate::instance::UserMeta;
+use crate::errors::{ChorusError, ChorusResult};
+use crate::instance::ChorusUser;
use crate::ratelimiter::ChorusRequest;
-use crate::types::{Message, MessageSendSchema, Snowflake};
+use crate::types::{
+ Channel, CreateGreetMessage, LimitType, Message, MessageAck, MessageModifySchema,
+ MessageSearchEndpoint, MessageSearchQuery, MessageSendSchema, Snowflake,
+};
impl Message {
+ /// Sends a message in the channel with the provided channel_id.
+ /// Returns the sent message.
+ ///
+ /// # Reference
+ /// See
pub async fn send(
- user: &mut UserMeta,
+ user: &mut ChorusUser,
channel_id: Snowflake,
mut message: MessageSendSchema,
- ) -> Result {
- let url_api = user.belongs_to.borrow().urls.api.clone();
+ ) -> ChorusResult {
+ let url_api = user.belongs_to.read().unwrap().urls.api.clone();
if message.attachments.is_none() {
let chorus_request = ChorusRequest {
request: Client::new()
- .post(format!("{}/channels/{}/messages/", url_api, channel_id))
- .bearer_auth(user.token())
- .body(to_string(&message).unwrap()),
+ .post(format!("{}/channels/{}/messages", url_api, channel_id))
+ .header("Authorization", user.token())
+ .body(to_string(&message).unwrap())
+ .header("Content-Type", "application/json"),
limit_type: LimitType::Channel(channel_id),
};
chorus_request.deserialize_response::(user).await
@@ -55,22 +64,462 @@ impl Message {
let chorus_request = ChorusRequest {
request: Client::new()
- .post(format!("{}/channels/{}/messages/", url_api, channel_id))
- .bearer_auth(user.token())
+ .post(format!("{}/channels/{}/messages", url_api, channel_id))
+ .header("Authorization", user.token())
.multipart(form),
limit_type: LimitType::Channel(channel_id),
};
chorus_request.deserialize_response::(user).await
}
}
+
+ /// Returns messages without the reactions key that match a search query in the guild or channel.
+ /// The messages that are direct results will have an extra hit key set to true.
+ /// If operating on a guild channel, this endpoint requires the `READ_MESSAGE_HISTORY`
+ /// permission to be present on the current user.
+ ///
+ /// If the guild/channel you are searching is not yet indexed, the endpoint will return a 202 accepted response.
+ /// In this case, the method will return a [`ChorusError::InvalidResponse`] error.
+ ///
+ /// # Reference:
+ /// See
+ pub(crate) async fn search(
+ endpoint: MessageSearchEndpoint,
+ query: MessageSearchQuery,
+ user: &mut ChorusUser,
+ ) -> ChorusResult> {
+ let limit_type = match &endpoint {
+ MessageSearchEndpoint::Channel(id) => LimitType::Channel(*id),
+ MessageSearchEndpoint::GuildChannel(id) => LimitType::Guild(*id),
+ };
+ let request = ChorusRequest {
+ limit_type,
+ request: Client::new()
+ .get(format!(
+ "{}/{}/messages/search",
+ &user.belongs_to.read().unwrap().urls.api,
+ endpoint
+ ))
+ .header("Authorization", user.token())
+ .header("Content-Type", "application/json")
+ .body(to_string(&query).unwrap()),
+ };
+ let result = request.send_request(user).await?;
+ let result_json = result.json::().await.unwrap();
+ if !result_json.is_object() {
+ return Err(search_error(result_json.to_string()));
+ }
+ let value_map = result_json.as_object().unwrap();
+ if let Some(messages) = value_map.get("messages") {
+ if let Ok(response) = from_value::>>(messages.clone()) {
+ let result_messages: Vec = response.into_iter().flatten().collect();
+ return Ok(result_messages);
+ }
+ }
+ // The code below might be incorrect. We'll cross that bridge when we come to it
+ if !value_map.contains_key("code") || !value_map.contains_key("retry_after") {
+ return Err(search_error(result_json.to_string()));
+ }
+ let code = value_map.get("code").unwrap().as_u64().unwrap();
+ let retry_after = value_map.get("retry_after").unwrap().as_u64().unwrap();
+ Err(ChorusError::NotFound {
+ error: format!(
+ "Index not yet available. Try again later. Code: {}. Retry after {}s",
+ code, retry_after
+ ),
+ })
+ }
+
+ /// Returns all pinned messages in the channel as a Vector of message objects without the reactions key.
+ /// # Reference:
+ /// See:
+ pub async fn get_sticky(
+ channel_id: Snowflake,
+ user: &mut ChorusUser,
+ ) -> ChorusResult> {
+ let chorus_request = ChorusRequest::new(
+ http::Method::GET,
+ format!(
+ "{}/channels/{}/pins",
+ user.belongs_to.read().unwrap().urls.api,
+ channel_id
+ )
+ .as_str(),
+ None,
+ None,
+ None,
+ Some(user),
+ LimitType::Channel(channel_id),
+ );
+ chorus_request
+ .deserialize_response::>(user)
+ .await
+ }
+
+ /// Pins a message in a channel. Requires the `MANAGE_MESSAGES` permission. Returns a 204 empty response on success.
+ /// The max pinned messages is 50.
+ ///
+ /// # Reference:
+ /// See:
+ pub async fn sticky(
+ channel_id: Snowflake,
+ message_id: Snowflake,
+ audit_log_reason: Option<&str>,
+ user: &mut ChorusUser,
+ ) -> ChorusResult<()> {
+ let request = ChorusRequest::new(
+ http::Method::PUT,
+ format!(
+ "{}/channels/{}/pins/{}",
+ user.belongs_to.read().unwrap().urls.api,
+ channel_id,
+ message_id
+ )
+ .as_str(),
+ None,
+ audit_log_reason,
+ None,
+ Some(user),
+ LimitType::Channel(channel_id),
+ );
+ request.handle_request_as_result(user).await
+ }
+
+ /// Unpins a message in a channel. Requires the `MANAGE_MESSAGES` permission. Returns a 204 empty response on success.
+ /// # Reference:
+ /// See:
+ pub async fn unsticky(
+ channel_id: Snowflake,
+ message_id: Snowflake,
+ audit_log_reason: Option<&str>,
+ user: &mut ChorusUser,
+ ) -> ChorusResult<()> {
+ let request = ChorusRequest::new(
+ http::Method::DELETE,
+ format!(
+ "{}/channels/{}/pins/{}",
+ user.belongs_to.read().unwrap().urls.api,
+ channel_id,
+ message_id
+ )
+ .as_str(),
+ None,
+ audit_log_reason,
+ None,
+ Some(user),
+ LimitType::Channel(channel_id),
+ );
+ request.handle_request_as_result(user).await
+ }
+
+ /// Returns a specific message object in the channel.
+ /// If operating on a guild channel, this endpoint requires the `READ_MESSAGE_HISTORY` permission to be present on the current user.
+ /// # Reference:
+ /// See:
+ pub async fn get(
+ channel_id: Snowflake,
+ message_id: Snowflake,
+ user: &mut ChorusUser,
+ ) -> ChorusResult {
+ let chorus_request = ChorusRequest {
+ request: Client::new()
+ .get(format!(
+ "{}/channels/{}/messages/{}",
+ user.belongs_to.read().unwrap().urls.api,
+ channel_id,
+ message_id
+ ))
+ .header("Authorization", user.token())
+ .header("Content-Type", "application/json"),
+ limit_type: LimitType::Channel(channel_id),
+ };
+ chorus_request.deserialize_response::(user).await
+ }
+
+ /// Posts a greet message to a channel. This endpoint requires the channel is a DM channel or you reply to a system message.
+ /// # Reference:
+ /// See:
+ pub async fn create_greet(
+ channel_id: Snowflake,
+ schema: CreateGreetMessage,
+ user: &mut ChorusUser,
+ ) -> ChorusResult {
+ let request = ChorusRequest::new(
+ http::Method::POST,
+ format!(
+ "{}/channels/{}/messages/greet",
+ user.belongs_to.read().unwrap().urls.api,
+ channel_id,
+ )
+ .as_str(),
+ Some(to_string(&schema).unwrap()),
+ None,
+ None,
+ Some(user),
+ LimitType::Channel(channel_id),
+ );
+ request.deserialize_response::(user).await
+ }
+
+ /// Sets the channel's latest acknowledged message (marks a message as read) for the current user.
+ /// The message ID parameter does not need to be a valid message ID, but it must be a valid snowflake.
+ /// If the message ID is being set to a message sent prior to the latest acknowledged one,
+ /// manual should be true or the resulting read state update should be ignored by clients (but is still saved), resulting in undefined behavior.
+ /// In this case, mention_count should also be set to the amount of mentions unacknowledged as it is not automatically calculated by Discord.
+ ///
+ /// Returns an optional token, which can be used as the new `ack` token for following `ack`s.
+ ///
+ /// # Reference:
+ /// See:
+ pub async fn acknowledge(
+ channel_id: Snowflake,
+ message_id: Snowflake,
+ schema: MessageAck,
+ user: &mut ChorusUser,
+ ) -> ChorusResult> {
+ let request = ChorusRequest::new(
+ http::Method::POST,
+ format!(
+ "{}/channels/{}/messages/{}/ack",
+ user.belongs_to.read().unwrap().urls.api,
+ channel_id,
+ message_id
+ )
+ .as_str(),
+ Some(to_string(&schema).unwrap()),
+ None,
+ None,
+ Some(user),
+ LimitType::Channel(channel_id),
+ );
+ request.deserialize_response::>(user).await
+ }
+
+ /// Crossposts a message in a News Channel to following channels.
+ /// This endpoint requires the `SEND_MESSAGES` permission, if the current user sent the message,
+ /// or additionally the `MANAGE_MESSAGES` permission, for all other messages, to be present for the current user.
+ ///
+ /// # Reference:
+ /// See
+ pub async fn crosspost(
+ channel_id: Snowflake,
+ message_id: Snowflake,
+ user: &mut ChorusUser,
+ ) -> ChorusResult {
+ let request = ChorusRequest::new(
+ http::Method::POST,
+ format!(
+ "{}/channels/{}/messages/{}/crosspost",
+ user.belongs_to.read().unwrap().urls.api,
+ channel_id,
+ message_id
+ )
+ .as_str(),
+ None,
+ None,
+ None,
+ Some(user),
+ LimitType::Channel(channel_id),
+ );
+ request.deserialize_response::(user).await
+ }
+
+ /// Hides a message from the feed of the guild the channel belongs to. Returns a 204 empty response on success.
+ ///
+ /// # Reference:
+ /// See
+ pub async fn hide_from_guild_feed(
+ channel_id: Snowflake,
+ message_id: Snowflake,
+ user: &mut ChorusUser,
+ ) -> ChorusResult<()> {
+ let url = format!(
+ "{}/channels/{}/messages/{}/hide-guild-feed",
+ user.belongs_to.read().unwrap().urls.api,
+ channel_id,
+ message_id
+ );
+ let chorus_request = ChorusRequest::new(
+ http::Method::DELETE,
+ &url,
+ None,
+ None,
+ None,
+ Some(user),
+ LimitType::Channel(channel_id),
+ );
+ chorus_request.handle_request_as_result(user).await
+ }
+
+ /// Edits a previously sent message. All fields can be edited by the original message author.
+ /// Other users can only edit flags and only if they have the MANAGE_MESSAGES permission in the corresponding channel.
+ /// When specifying flags, ensure to include all previously set flags/bits in addition to ones that you are modifying.
+ /// When the content field is edited, the mentions array in the message object will be reconstructed from scratch based on the new content.
+ /// The allowed_mentions field of the edit request controls how this happens.
+ /// If there is no explicit allowed_mentions in the edit request, the content will be parsed with default allowances, that is,
+ /// without regard to whether or not an allowed_mentions was present in the request that originally created the message.
+ ///
+ /// # Reference:
+ /// See:
+ pub async fn modify(
+ channel_id: Snowflake,
+ message_id: Snowflake,
+ schema: MessageModifySchema,
+ user: &mut ChorusUser,
+ ) -> ChorusResult {
+ let url = format!(
+ "{}/channels/{}/messages/{}",
+ user.belongs_to.read().unwrap().urls.api,
+ channel_id,
+ message_id
+ );
+ let chorus_request = ChorusRequest::new(
+ http::Method::PATCH,
+ &url,
+ Some(to_string(&schema).unwrap()),
+ None,
+ None,
+ Some(user),
+ LimitType::Channel(channel_id),
+ );
+ chorus_request.deserialize_response::(user).await
+ }
+
+ /// Deletes a message. If operating on a guild channel and trying to delete a message that was not sent by the current user,
+ /// this endpoint requires the `MANAGE_MESSAGES` permission. Returns a 204 empty response on success.
+ pub async fn delete(
+ channel_id: Snowflake,
+ message_id: Snowflake,
+ audit_log_reason: Option,
+ user: &mut ChorusUser,
+ ) -> ChorusResult<()> {
+ let url = format!(
+ "{}/channels/{}/messages/{}",
+ user.belongs_to.read().unwrap().urls.api,
+ channel_id,
+ message_id
+ );
+
+ let chorus_request = ChorusRequest::new(
+ http::Method::DELETE,
+ &url,
+ None,
+ audit_log_reason.as_deref(),
+ None,
+ Some(user),
+ LimitType::Channel(channel_id),
+ );
+
+ chorus_request.handle_request_as_result(user).await
+ }
+
+ /// Deletes multiple messages in a single request. This endpoint can only be used on guild channels and requires the MANAGE_MESSAGES permission.
+ /// Returns a 204 empty response on success.
+ ///
+ /// **This endpoint will not delete messages older than 2 weeks, and will fail if any message provided is older than that or if any duplicate message IDs are provided.**
+ ///
+ /// **This endpoint is not usable by user accounts.** (At least according to Discord.com. Spacebar behaviour may differ.)
+ ///
+ /// # Reference:
+ /// See:
+ pub async fn bulk_delete(
+ channel_id: Snowflake,
+ messages: Vec,
+ audit_log_reason: Option,
+ user: &mut ChorusUser,
+ ) -> ChorusResult<()> {
+ if messages.len() < 2 {
+ return Err(ChorusError::InvalidArguments {
+ error: "`messages` must contain at least 2 entries.".to_string(),
+ });
+ }
+ let request = ChorusRequest::new(
+ http::Method::POST,
+ format!(
+ "{}/channels/{}/messages/bulk-delete",
+ user.belongs_to.read().unwrap().urls.api,
+ channel_id,
+ )
+ .as_str(),
+ Some(to_string(&messages).unwrap()),
+ audit_log_reason.as_deref(),
+ None,
+ Some(user),
+ LimitType::Channel(channel_id),
+ );
+ request.handle_request_as_result(user).await
+ }
+
+ /// Acknowledges the currently pinned messages in a channel. Returns a 204 empty response on success.
+ ///
+ /// # Reference:
+ /// See:
+ pub async fn acknowledge_pinned(
+ channel_id: Snowflake,
+ user: &mut ChorusUser,
+ ) -> ChorusResult<()> {
+ let chorus_request = ChorusRequest::new(
+ http::Method::POST,
+ format!(
+ "{}/channels/{}/pins/ack",
+ user.belongs_to.read().unwrap().urls.api,
+ channel_id,
+ )
+ .as_str(),
+ None,
+ None,
+ None,
+ Some(user),
+ LimitType::Channel(channel_id),
+ );
+
+ chorus_request.handle_request_as_result(user).await
+ }
}
-impl UserMeta {
+fn search_error(result_text: String) -> ChorusError {
+ ChorusError::InvalidResponse {
+ error: format!(
+ "Got unexpected Response, or Response which is not valid JSON. Response: \n{}",
+ result_text
+ ),
+ }
+}
+
+impl ChorusUser {
+ /// Sends a message in the channel with the provided channel_id.
+ /// Returns the sent message.
+ ///
+ /// # Notes
+ /// Shorthand call for [`Message::send`]
+ ///
+ /// # Reference
+ /// See
pub async fn send_message(
&mut self,
message: MessageSendSchema,
channel_id: Snowflake,
- ) -> Result {
+ ) -> ChorusResult {
Message::send(self, channel_id, message).await
}
}
+
+impl Channel {
+ /// Returns messages without the reactions key that match a search query in the channel.
+ /// The messages that are direct results will have an extra hit key set to true.
+ /// If operating on a guild channel, this endpoint requires the `READ_MESSAGE_HISTORY`
+ /// permission to be present on the current user.
+ ///
+ /// If the guild/channel you are searching is not yet indexed, the endpoint will return a 202 accepted response.
+ /// In this case, the method will return a [`ChorusError::InvalidResponse`] error.
+ ///
+ /// # Reference:
+ /// See
+ pub async fn search_messages(
+ channel_id: Snowflake,
+ query: MessageSearchQuery,
+ user: &mut ChorusUser,
+ ) -> ChorusResult> {
+ Message::search(MessageSearchEndpoint::Channel(channel_id), query, user).await
+ }
+}
diff --git a/src/api/channels/permissions.rs b/src/api/channels/permissions.rs
index bc666ff..5360890 100644
--- a/src/api/channels/permissions.rs
+++ b/src/api/channels/permissions.rs
@@ -2,33 +2,32 @@ use reqwest::Client;
use serde_json::to_string;
use crate::{
- api::LimitType,
errors::{ChorusError, ChorusResult},
- instance::UserMeta,
+ instance::ChorusUser,
ratelimiter::ChorusRequest,
- types::{self, PermissionOverwrite, Snowflake},
+ types::{self, LimitType, PermissionOverwrite, Snowflake},
};
impl types::Channel {
- /// Edits the permission overwrites for a channel.
+ /// Edits the permission overwrites for a user or role in a channel.
///
- /// # Arguments
+ /// Only usable for guild channels.
///
- /// * `user` - A mutable reference to a [`UserMeta`] instance.
- /// * `channel_id` - A string slice representing the ID of the channel.
- /// * `overwrite` - A [`PermissionOverwrite`] instance representing the new permission overwrites.
+ /// Requires the [`MANAGE_ROLES`](crate::types::PermissionFlags::MANAGE_ROLES) permission.
+ /// Only permissions you have in the guild or parent channel (if applicable) can be allowed/denied
+ /// (unless you have a [`MANAGE_ROLES`](crate::types::PermissionFlags::MANAGE_ROLES) overwrite in the channel).
///
- /// # Returns
- ///
- /// This function returns a result that is either [`Ok(())`] if the request is successful, or an [`Err(ChorusLibError)`].
- pub async fn edit_permissions(
- user: &mut UserMeta,
+ /// # Reference
+ /// See
+ pub async fn modify_permissions(
+ user: &mut ChorusUser,
channel_id: Snowflake,
+ audit_log_reason: Option,
overwrite: PermissionOverwrite,
) -> ChorusResult<()> {
let url = format!(
"{}/channels/{}/permissions/{}",
- user.belongs_to.borrow_mut().urls.api,
+ user.belongs_to.read().unwrap().urls.api,
channel_id,
overwrite.id
);
@@ -40,39 +39,51 @@ impl types::Channel {
});
}
};
+ let mut request = Client::new()
+ .put(url)
+ .header("Authorization", user.token())
+ .header("Content-Type", "application/json")
+ .body(body);
+ if let Some(reason) = audit_log_reason {
+ request = request.header("X-Audit-Log-Reason", reason);
+ }
let chorus_request = ChorusRequest {
- request: Client::new().put(url).bearer_auth(user.token()).body(body),
+ request,
limit_type: LimitType::Channel(channel_id),
};
chorus_request.handle_request_as_result(user).await
}
- /// Deletes a permission overwrite for a channel.
+ /// Deletes a permission overwrite for a user or role in a channel.
///
- /// # Arguments
+ /// Only usable for guild channels.
///
- /// * `user` - A mutable reference to a [`UserMeta`] instance.
- /// * `channel_id` - A string slice representing the ID of the channel.
- /// * `overwrite_id` - A string slice representing the ID of the permission overwrite to delete.
+ /// Requires the [`MANAGE_ROLES`](crate::types::PermissionFlags::MANAGE_ROLES) permission.
///
- /// # Returns
- ///
- /// This function returns a Result that is either [`Ok(())`] if the request is successfulm or an [`Err(ChorusLibError)`].
+ /// # Reference
+ /// See
pub async fn delete_permission(
- user: &mut UserMeta,
+ user: &mut ChorusUser,
channel_id: Snowflake,
overwrite_id: Snowflake,
) -> ChorusResult<()> {
let url = format!(
"{}/channels/{}/permissions/{}",
- user.belongs_to.borrow_mut().urls.api,
+ user.belongs_to.read().unwrap().urls.api,
channel_id,
overwrite_id
);
- let chorus_request = ChorusRequest {
- request: Client::new().delete(url).bearer_auth(user.token()),
- limit_type: LimitType::Channel(channel_id),
- };
- chorus_request.handle_request_as_result(user).await
+
+ let request = ChorusRequest::new(
+ http::Method::DELETE,
+ &url,
+ None,
+ None,
+ None,
+ Some(user),
+ LimitType::Channel(channel_id),
+ );
+
+ request.handle_request_as_result(user).await
}
}
diff --git a/src/api/channels/reactions.rs b/src/api/channels/reactions.rs
index 35dbb94..94d3087 100644
--- a/src/api/channels/reactions.rs
+++ b/src/api/channels/reactions.rs
@@ -1,16 +1,12 @@
-use reqwest::Client;
-
use crate::{
- api::LimitType,
errors::ChorusResult,
- instance::UserMeta,
+ instance::ChorusUser,
ratelimiter::ChorusRequest,
- types::{self, PublicUser, Snowflake},
+ types::{self, LimitType, PublicUser, Snowflake},
};
-/**
-Useful metadata for working with [`types::Reaction`], bundled together nicely.
- */
+/// Useful metadata for working with [`types::Reaction`], bundled together nicely.
+#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ReactionMeta {
pub message_id: types::Snowflake,
pub channel_id: types::Snowflake,
@@ -18,169 +14,189 @@ pub struct ReactionMeta {
impl ReactionMeta {
/// Deletes all reactions for a message.
- /// This endpoint requires the `MANAGE_MESSAGES` permission to be present on the current user.
- /// # Arguments
- /// * `user` - A mutable reference to a [`UserMeta`] instance.
- /// # Returns
- /// A `Result` [`()`] [`crate::errors::ChorusLibError`] if something went wrong.
- /// Fires a `Message Reaction Remove All` Gateway event.
+ ///
+ /// This endpoint requires the [`MANAGE_MESSAGES`](crate::types::PermissionFlags::MANAGE_MESSAGES) permission.
+ ///
/// # Reference
- /// See [https://discord.com/developers/docs/resources/channel#delete-all-reactions](https://discord.com/developers/docs/resources/channel#delete-all-reactions)
- pub async fn delete_all(&self, user: &mut UserMeta) -> ChorusResult<()> {
+ /// See
+ pub async fn delete_all(&self, user: &mut ChorusUser) -> ChorusResult<()> {
let url = format!(
- "{}/channels/{}/messages/{}/reactions/",
- user.belongs_to.borrow().urls.api,
+ "{}/channels/{}/messages/{}/reactions",
+ user.belongs_to.read().unwrap().urls.api,
self.channel_id,
self.message_id
);
- let chorus_request = ChorusRequest {
- request: Client::new().delete(url).bearer_auth(user.token()),
- limit_type: LimitType::Channel(self.channel_id),
- };
- chorus_request.handle_request_as_result(user).await
+
+ let request = ChorusRequest::new(
+ http::Method::DELETE,
+ &url,
+ None,
+ None,
+ None,
+ Some(user),
+ LimitType::Channel(self.channel_id),
+ );
+
+ request.handle_request_as_result(user).await
}
/// Gets a list of users that reacted with a specific emoji to a message.
- /// # Arguments
- /// * `emoji` - A string slice containing the emoji to search for. The emoji must be URL Encoded or
- /// the request will fail with 10014: Unknown Emoji. To use custom emoji, you must encode it in the
- /// format name:id with the emoji name and emoji id.
- /// * `user` - A mutable reference to a [`UserMeta`] instance.
- /// # Returns
- /// A Result that is [`Err(crate::errors::ChorusLibError)`] if something went wrong.
- /// # Reference
- /// See [https://discord.com/developers/docs/resources/channel#get-reactions](https://discord.com/developers/docs/resources/channel#get-reactions)
- pub async fn get(&self, emoji: &str, user: &mut UserMeta) -> ChorusResult> {
- let url = format!(
- "{}/channels/{}/messages/{}/reactions/{}/",
- user.belongs_to.borrow().urls.api,
- self.channel_id,
- self.message_id,
- emoji
- );
- let chorus_request = ChorusRequest {
- request: Client::new().get(url).bearer_auth(user.token()),
- limit_type: LimitType::Channel(self.channel_id),
- };
- chorus_request
- .deserialize_response::>(user)
- .await
- }
-
- /// Deletes all the reactions for a given `emoji` on a message. This endpoint requires the
- /// MANAGE_MESSAGES permission to be present on the current user.
- /// # Arguments
- /// * `emoji` - A string slice containing the emoji to delete. The `emoji` must be URL Encoded or
- /// the request will fail with 10014: Unknown Emoji. To use custom emoji, you must encode it in the
- /// format name:id with the emoji name and emoji id.
- /// * `user` - A mutable reference to a [`UserMeta`] instance.
- /// # Returns
- /// A Result that is [`Err(crate::errors::ChorusLibError)`] if something went wrong.
- /// Fires a `Message Reaction Remove Emoji` Gateway event.
- /// # Reference
- /// See [https://discord.com/developers/docs/resources/channel#delete-all-reactions-for-emoji](https://discord.com/developers/docs/resources/channel#delete-all-reactions-for-emoji)
- pub async fn delete_emoji(&self, emoji: &str, user: &mut UserMeta) -> ChorusResult<()> {
- let url = format!(
- "{}/channels/{}/messages/{}/reactions/{}/",
- user.belongs_to.borrow().urls.api,
- self.channel_id,
- self.message_id,
- emoji
- );
- let chorus_request = ChorusRequest {
- request: Client::new().delete(url).bearer_auth(user.token()),
- limit_type: LimitType::Channel(self.channel_id),
- };
- chorus_request.handle_request_as_result(user).await
- }
-
- /// Create a reaction for the message.
- /// This endpoint requires the READ_MESSAGE_HISTORY permission
- /// to be present on the current user. Additionally, if nobody else has reacted to the message using
- /// this emoji, this endpoint requires the ADD_REACTIONS permission to be present on the current
- /// user.
- /// # Arguments
- /// * `emoji` - A string slice containing the emoji to delete. The `emoji` must be URL Encoded or
- /// the request will fail with 10014: Unknown Emoji. To use custom emoji, you must encode it in the
- /// format name:id with the emoji name and emoji id.
- /// * `user` - A mutable reference to a [`UserMeta`] instance.
- /// # Returns
- /// A `Result` containing [`()`] or a [`crate::errors::ChorusLibError`].
- /// # Reference
- /// See [https://discord.com/developers/docs/resources/channel#create-reaction](https://discord.com/developers/docs/resources/channel#create-reaction)
///
- pub async fn create(&self, emoji: &str, user: &mut UserMeta) -> ChorusResult<()> {
+ /// The emoji must be URL Encoded or the request will fail with 10014: Unknown Emoji.
+ /// To use custom emoji, the format of the emoji string must be name:id.
+ ///
+ /// # Reference
+ /// See
+ pub async fn get(&self, emoji: &str, user: &mut ChorusUser) -> ChorusResult> {
let url = format!(
- "{}/channels/{}/messages/{}/reactions/{}/@me/",
- user.belongs_to.borrow().urls.api,
+ "{}/channels/{}/messages/{}/reactions/{}",
+ user.belongs_to.read().unwrap().urls.api,
self.channel_id,
self.message_id,
emoji
);
- let chorus_request = ChorusRequest {
- request: Client::new().put(url).bearer_auth(user.token()),
- limit_type: LimitType::Channel(self.channel_id),
- };
- chorus_request.handle_request_as_result(user).await
+
+ let request = ChorusRequest::new(
+ http::Method::GET,
+ &url,
+ None,
+ None,
+ None,
+ Some(user),
+ LimitType::Channel(self.channel_id),
+ );
+
+ request.deserialize_response::>(user).await
}
- /// Delete a reaction the current user has made for the message.
- /// # Arguments
- /// * `emoji` - A string slice containing the emoji to delete. The `emoji` must be URL Encoded or
- /// the request will fail with 10014: Unknown Emoji. To use custom emoji, you must encode it in the
- /// format name:id with the emoji name and emoji id.
- /// * `user` - A mutable reference to a [`UserMeta`] instance.
- /// # Returns
- /// A `Result` containing [`()`] or a [`crate::errors::ChorusLibError`].
- /// Fires a `Message Reaction Remove` Gateway event.
+ /// Deletes all the reactions for a given emoji on a message.
+ ///
+ /// This endpoint requires the [`MANAGE_MESSAGES`](crate::types::PermissionFlags::MANAGE_MESSAGES) permission.
+ ///
+ /// The emoji must be URL Encoded or the request will fail with 10014: Unknown Emoji.
+ /// To use custom emoji, the format of the emoji string must be name:id.
+ ///
/// # Reference
- /// See [https://discord.com/developers/docs/resources/channel#delete-own-reaction](https://discord.com/developers/docs/resources/channel#delete-own-reaction)
- pub async fn remove(&self, emoji: &str, user: &mut UserMeta) -> ChorusResult<()> {
+ /// See
+ pub async fn delete_emoji(&self, emoji: &str, user: &mut ChorusUser) -> ChorusResult<()> {
let url = format!(
- "{}/channels/{}/messages/{}/reactions/{}/@me/",
- user.belongs_to.borrow().urls.api,
+ "{}/channels/{}/messages/{}/reactions/{}",
+ user.belongs_to.read().unwrap().urls.api,
self.channel_id,
self.message_id,
emoji
);
- let chorus_request = ChorusRequest {
- request: Client::new().delete(url).bearer_auth(user.token()),
- limit_type: LimitType::Channel(self.channel_id),
- };
- chorus_request.handle_request_as_result(user).await
+
+ let request = ChorusRequest::new(
+ http::Method::DELETE,
+ &url,
+ None,
+ None,
+ None,
+ Some(user),
+ LimitType::Channel(self.channel_id),
+ );
+
+ request.handle_request_as_result(user).await
}
- /// Delete a user's reaction to a message.
- /// This endpoint requires the MANAGE_MESSAGES permission to be present on the current user.
- /// # Arguments
- /// * `user_id` - ID of the user whose reaction is to be deleted.
- /// * `emoji` - A string slice containing the emoji to delete. The `emoji` must be URL Encoded or
- /// the request will fail with 10014: Unknown Emoji. To use custom emoji, you must encode it in the
- /// format name:id with the emoji name and emoji id.
- /// * `user` - A mutable reference to a [`UserMeta`] instance.
- /// # Returns
- /// A `Result` containing [`()`] or a [`crate::errors::ChorusLibError`].
- /// Fires a Message Reaction Remove Gateway event.
+ /// Create a reaction on a message.
+ ///
+ /// This endpoint requires the [`READ_MESSAGE_HISTORY`](crate::types::PermissionFlags::READ_MESSAGE_HISTORY) permission.
+ ///
+ /// Additionally, if nobody else has reacted to the message using this emoji,
+ /// this endpoint requires the [`ADD_REACTIONS`](crate::types::PermissionFlags::ADD_REACTIONS) permission.
+ ///
+ /// The emoji must be URL Encoded or the request will fail with 10014: Unknown Emoji.
+ /// To use custom emoji, the format of the emoji string must be `name:id`.
+ ///
/// # Reference
- /// See [https://discord.com/developers/docs/resources/channel#delete-own-reaction](https://discord.com/developers/docs/resources/channel#delete-own-reaction)
+ /// See
+ pub async fn create(&self, emoji: &str, user: &mut ChorusUser) -> ChorusResult<()> {
+ let url = format!(
+ "{}/channels/{}/messages/{}/reactions/{}/@me",
+ user.belongs_to.read().unwrap().urls.api,
+ self.channel_id,
+ self.message_id,
+ emoji
+ );
+
+ let request = ChorusRequest::new(
+ http::Method::PUT,
+ &url,
+ None,
+ None,
+ None,
+ Some(user),
+ LimitType::Channel(self.channel_id),
+ );
+
+ request.handle_request_as_result(user).await
+ }
+
+ /// Deletes a reaction the current user has made to the message.
+ ///
+ /// The reaction emoji must be URL Encoded or the request will fail with 10014: Unknown Emoji.
+ /// To use custom emoji, the format of the emoji string must be name:id.
+ ///
+ /// # Reference
+ /// See
+ pub async fn remove(&self, emoji: &str, user: &mut ChorusUser) -> ChorusResult<()> {
+ let url = format!(
+ "{}/channels/{}/messages/{}/reactions/{}/@me",
+ user.belongs_to.read().unwrap().urls.api,
+ self.channel_id,
+ self.message_id,
+ emoji
+ );
+
+ let request = ChorusRequest::new(
+ http::Method::DELETE,
+ &url,
+ None,
+ None,
+ None,
+ Some(user),
+ LimitType::Channel(self.channel_id),
+ );
+
+ request.handle_request_as_result(user).await
+ }
+
+ /// Deletes a user's reaction to a message.
+ ///
+ /// This endpoint requires the [`MANAGE_MESSAGES`](crate::types::PermissionFlags::MANAGE_MESSAGES) permission.
+ ///
+ /// The reaction emoji must be URL Encoded or the request will fail with 10014: Unknown Emoji.
+ /// To use custom emoji, the format of the emoji string must be name:id.
+ ///
+ /// # Reference
+ /// See
pub async fn delete_user(
&self,
user_id: Snowflake,
emoji: &str,
- user: &mut UserMeta,
+ user: &mut ChorusUser,
) -> ChorusResult<()> {
let url = format!(
"{}/channels/{}/messages/{}/reactions/{}/{}",
- user.belongs_to.borrow().urls.api,
+ user.belongs_to.read().unwrap().urls.api,
self.channel_id,
self.message_id,
emoji,
user_id
);
- let chorus_request = ChorusRequest {
- request: Client::new().delete(url).bearer_auth(user.token()),
- limit_type: LimitType::Channel(self.channel_id),
- };
- chorus_request.handle_request_as_result(user).await
+
+ let request = ChorusRequest::new(
+ http::Method::DELETE,
+ &url,
+ None,
+ None,
+ None,
+ Some(user),
+ LimitType::Channel(self.channel_id),
+ );
+
+ request.handle_request_as_result(user).await
}
}
diff --git a/src/api/guilds/guilds.rs b/src/api/guilds/guilds.rs
index 3654698..b433c84 100644
--- a/src/api/guilds/guilds.rs
+++ b/src/api/guilds/guilds.rs
@@ -2,57 +2,41 @@ use reqwest::Client;
use serde_json::from_str;
use serde_json::to_string;
-use crate::api::LimitType;
use crate::errors::ChorusError;
use crate::errors::ChorusResult;
-use crate::instance::UserMeta;
+use crate::instance::ChorusUser;
use crate::ratelimiter::ChorusRequest;
-use crate::types::Snowflake;
-use crate::types::{Channel, ChannelCreateSchema, Guild, GuildCreateSchema};
+use crate::types::{
+ Channel, ChannelCreateSchema, Guild, GuildBanCreateSchema, GuildBansQuery, GuildCreateSchema,
+ GuildMember, GuildMemberSearchSchema, GuildModifySchema, GuildPreview, LimitType,
+ ModifyGuildMemberProfileSchema, ModifyGuildMemberSchema, UserProfileMetadata,
+};
+use crate::types::{GuildBan, Snowflake};
impl Guild {
- /// Creates a new guild with the given parameters.
- ///
- /// # Arguments
- ///
- /// * `user` - A mutable reference to the user creating the guild.
- /// * `instance` - A mutable reference to the instance where the guild will be created.
- /// * `guild_create_schema` - A reference to the schema containing the guild creation parameters.
- ///
- /// # Returns
- ///
- /// A `Result` containing the object of the newly created guild, or an error if the request fails.
- ///
- /// # Errors
- ///
- /// Returns an `ChorusLibError` if the request fails.
+ /// Creates a new guild.
///
+ /// # Reference
+ /// See
pub async fn create(
- user: &mut UserMeta,
+ user: &mut ChorusUser,
guild_create_schema: GuildCreateSchema,
) -> ChorusResult {
- let url = format!("{}/guilds/", user.belongs_to.borrow().urls.api);
+ let url = format!("{}/guilds", user.belongs_to.read().unwrap().urls.api);
let chorus_request = ChorusRequest {
request: Client::new()
.post(url.clone())
- .bearer_auth(user.token.clone())
+ .header("Authorization", user.token.clone())
+ .header("Content-Type", "application/json")
.body(to_string(&guild_create_schema).unwrap()),
limit_type: LimitType::Global,
};
chorus_request.deserialize_response::(user).await
}
- /// Deletes a guild.
+ /// Deletes a guild by its id.
///
- /// # Arguments
- ///
- /// * `user` - A mutable reference to a `User` instance.
- /// * `instance` - A mutable reference to an `Instance` instance.
- /// * `guild_id` - ID of the guild to delete.
- ///
- /// # Returns
- ///
- /// An `Result` containing an `ChorusLibError` if an error occurred during the request, otherwise `()`.
+ /// User must be the owner.
///
/// # Example
///
@@ -61,65 +45,63 @@ impl Guild {
/// let mut instance = Instance::new();
/// let guild_id = String::from("1234567890");
///
- /// match Guild::delete(&mut user, &mut instance, guild_id) {
- /// Some(e) => println!("Error deleting guild: {:?}", e),
- /// None => println!("Guild deleted successfully"),
+ /// match Guild::delete(&mut user, guild_id) {
+ /// Err(e) => println!("Error deleting guild: {:?}", e),
+ /// Ok(_) => println!("Guild deleted successfully"),
/// }
/// ```
- pub async fn delete(user: &mut UserMeta, guild_id: Snowflake) -> ChorusResult<()> {
+ ///
+ /// # Reference
+ /// See
+ pub async fn delete(user: &mut ChorusUser, guild_id: Snowflake) -> ChorusResult<()> {
let url = format!(
- "{}/guilds/{}/delete/",
- user.belongs_to.borrow().urls.api,
+ "{}/guilds/{}/delete",
+ user.belongs_to.read().unwrap().urls.api,
guild_id
);
let chorus_request = ChorusRequest {
request: Client::new()
.post(url.clone())
- .bearer_auth(user.token.clone()),
+ .header("Authorization", user.token.clone())
+ .header("Content-Type", "application/json"),
limit_type: LimitType::Global,
};
chorus_request.handle_request_as_result(user).await
}
- /// Sends a request to create a new channel in the guild.
+ /// Creates a new channel in a guild.
///
- /// # Arguments
+ /// Requires the [MANAGE_CHANNELS](crate::types::PermissionFlags::MANAGE_CHANNELS) permission.
///
- /// * `url_api` - The base URL for the Discord API.
- /// * `token` - A Discord bot token.
- /// * `schema` - A `ChannelCreateSchema` struct containing the properties of the new channel.
- /// * `limits_user` - A mutable reference to a `Limits` struct containing the user's rate limits.
- /// * `limits_instance` - A mutable reference to a `Limits` struct containing the instance's rate limits.
+ /// # Notes
+ /// This method is a wrapper for [Channel::create].
///
- /// # Returns
- ///
- /// A `Result` containing a `reqwest::Response` if the request was successful, or an `ChorusLibError` if there was an error.
+ /// # Reference
+ /// See
pub async fn create_channel(
&self,
- user: &mut UserMeta,
+ user: &mut ChorusUser,
+ audit_log_reason: Option,
schema: ChannelCreateSchema,
) -> ChorusResult {
- Channel::create(user, self.id, schema).await
+ Channel::create(user, self.id, audit_log_reason, schema).await
}
- /// Returns a `Result` containing a vector of `Channel` structs if the request was successful, or an `ChorusLibError` if there was an error.
+ /// Returns a list of the guild's channels.
///
- /// # Arguments
+ /// Doesn't include threads.
///
- /// * `url_api` - A string slice that holds the URL of the API.
- /// * `token` - A string slice that holds the authorization token.
- /// * `limits_user` - A mutable reference to a `Limits` struct containing the user's rate limits.
- /// * `limits_instance` - A mutable reference to a `Limits` struct containing the instance's rate limits.
- ///
- pub async fn channels(&self, user: &mut UserMeta) -> ChorusResult> {
+ /// # Reference
+ /// See
+ pub async fn channels(&self, user: &mut ChorusUser) -> ChorusResult> {
let chorus_request = ChorusRequest {
request: Client::new()
.get(format!(
- "{}/guilds/{}/channels/",
- user.belongs_to.borrow().urls.api,
+ "{}/guilds/{}/channels",
+ user.belongs_to.read().unwrap().urls.api,
self.id
))
- .bearer_auth(user.token()),
+ .header("Authorization", user.token()),
limit_type: LimitType::Channel(self.id),
};
let result = chorus_request.send_request(user).await?;
@@ -141,61 +123,381 @@ impl Guild {
};
}
- /// Returns a `Result` containing a `Guild` struct if the request was successful, or an `ChorusLibError` if there was an error.
+ /// Fetches a guild by its id.
///
- /// # Arguments
- ///
- /// * `url_api` - A string slice that holds the URL of the API.
- /// * `guild_id` - ID of the guild.
- /// * `token` - A string slice that holds the authorization token.
- /// * `limits_user` - A mutable reference to a `Limits` struct containing the user's rate limits.
- /// * `limits_instance` - A mutable reference to a `Limits` struct containing the instance's rate limits.
- ///
- pub async fn get(guild_id: Snowflake, user: &mut UserMeta) -> ChorusResult {
+ /// # Reference
+ /// See
+ pub async fn get(guild_id: Snowflake, user: &mut ChorusUser) -> ChorusResult {
let chorus_request = ChorusRequest {
request: Client::new()
.get(format!(
- "{}/guilds/{}/",
- user.belongs_to.borrow().urls.api,
+ "{}/guilds/{}",
+ user.belongs_to.read().unwrap().urls.api,
guild_id
))
- .bearer_auth(user.token()),
+ .header("Authorization", user.token()),
limit_type: LimitType::Guild(guild_id),
};
let response = chorus_request.deserialize_response::(user).await?;
Ok(response)
}
+
+ pub async fn create_ban(
+ guild_id: Snowflake,
+ user_id: Snowflake,
+ audit_log_reason: Option,
+ schema: GuildBanCreateSchema,
+ user: &mut ChorusUser,
+ ) -> ChorusResult<()> {
+ // FIXME: Return GuildBan instead of (). Requires to be resolved.
+ let request = ChorusRequest::new(
+ http::Method::PUT,
+ format!(
+ "{}/guilds/{}/bans/{}",
+ user.belongs_to.read().unwrap().urls.api,
+ guild_id,
+ user_id
+ )
+ .as_str(),
+ Some(to_string(&schema).unwrap()),
+ audit_log_reason.as_deref(),
+ None,
+ Some(user),
+ LimitType::Guild(guild_id),
+ );
+ request.handle_request_as_result(user).await
+ }
+
+ /// # Reference
+ ///
+ pub async fn modify(
+ guild_id: Snowflake,
+ schema: GuildModifySchema,
+ user: &mut ChorusUser,
+ ) -> ChorusResult {
+ let chorus_request = ChorusRequest {
+ request: Client::new()
+ .patch(format!(
+ "{}/guilds/{}",
+ user.belongs_to.read().unwrap().urls.api,
+ guild_id,
+ ))
+ .header("Authorization", user.token())
+ .header("Content-Type", "application/json")
+ .body(to_string(&schema).unwrap()),
+ limit_type: LimitType::Guild(guild_id),
+ };
+ let response = chorus_request.deserialize_response::(user).await?;
+ Ok(response)
+ }
+
+ /// Returns a guild preview object for the given guild ID. If the user is not in the guild, the guild must be discoverable.
+ /// # Reference:
+ ///
+ /// See
+ pub async fn get_preview(
+ guild_id: Snowflake,
+ user: &mut ChorusUser,
+ ) -> ChorusResult {
+ let chorus_request = ChorusRequest {
+ request: Client::new()
+ .patch(format!(
+ "{}/guilds/{}/preview",
+ user.belongs_to.read().unwrap().urls.api,
+ guild_id,
+ ))
+ .header("Authorization", user.token())
+ .header("Content-Type", "application/json"),
+ limit_type: LimitType::Guild(guild_id),
+ };
+ let response = chorus_request
+ .deserialize_response::(user)
+ .await?;
+ Ok(response)
+ }
+
+ /// Returns a list of guild member objects that are members of the guild.
+ ///
+ /// # Reference
+ /// See
+ pub async fn get_members(
+ guild_id: Snowflake,
+ user: &mut ChorusUser,
+ ) -> ChorusResult> {
+ let request = ChorusRequest::new(
+ http::Method::GET,
+ format!(
+ "{}/guilds/{}/members",
+ user.belongs_to.read().unwrap().urls.api,
+ guild_id,
+ )
+ .as_str(),
+ None,
+ None,
+ None,
+ Some(user),
+ LimitType::Guild(guild_id),
+ );
+ request.deserialize_response::>(user).await
+ }
+
+ /// Returns a list of guild member objects whose username or nickname starts with a provided string.
+ ///
+ /// # Reference:
+ /// See
+ pub async fn search_members(
+ guild_id: Snowflake,
+ query: GuildMemberSearchSchema,
+ user: &mut ChorusUser,
+ ) -> ChorusResult> {
+ let mut request = ChorusRequest::new(
+ http::Method::GET,
+ format!(
+ "{}/guilds/{}/members/search",
+ user.belongs_to.read().unwrap().urls.api,
+ guild_id,
+ )
+ .as_str(),
+ None,
+ None,
+ None,
+ Some(user),
+ LimitType::Guild(guild_id),
+ );
+ request.request = request
+ .request
+ .query(&[("query", to_string(&query).unwrap())]);
+ request.deserialize_response::>(user).await
+ }
+
+ /// Removes a member from a guild. Requires the KICK_MEMBERS permission. Returns a 204 empty response on success.
+ ///
+ /// # Reference
+ /// See
+ pub async fn remove_member(
+ guild_id: Snowflake,
+ member_id: Snowflake,
+ audit_log_reason: Option,
+ user: &mut ChorusUser,
+ ) -> ChorusResult<()> {
+ let request = ChorusRequest::new(
+ http::Method::DELETE,
+ format!(
+ "{}/guilds/{}/members/{}",
+ user.belongs_to.read().unwrap().urls.api,
+ guild_id,
+ member_id,
+ )
+ .as_str(),
+ None,
+ audit_log_reason.as_deref(),
+ None,
+ Some(user),
+ LimitType::Guild(guild_id),
+ );
+ request.handle_request_as_result(user).await
+ }
+
+ /// Modifies attributes of a guild member. Returns the updated guild member object on success.
+ /// For required Permissions and an API reference, see:
+ ///
+ /// # Reference:
+ ///
+ pub async fn modify_member(
+ guild_id: Snowflake,
+ member_id: Snowflake,
+ schema: ModifyGuildMemberSchema,
+ audit_log_reason: Option,
+ user: &mut ChorusUser,
+ ) -> ChorusResult {
+ let request = ChorusRequest::new(
+ http::Method::PATCH,
+ format!(
+ "{}/guilds/{}/members/{}",
+ user.belongs_to.read().unwrap().urls.api,
+ guild_id,
+ member_id,
+ )
+ .as_str(),
+ Some(to_string(&schema).unwrap()),
+ audit_log_reason.as_deref(),
+ None,
+ Some(user),
+ LimitType::Guild(guild_id),
+ );
+ request.deserialize_response::(user).await
+ }
+
+ /// Modifies the current user's member in the guild.
+ ///
+ /// # Reference:
+ /// See
+ pub async fn modify_current_member(
+ guild_id: Snowflake,
+ schema: ModifyGuildMemberSchema,
+ audit_log_reason: Option,
+ user: &mut ChorusUser,
+ ) -> ChorusResult {
+ let request = ChorusRequest::new(
+ http::Method::PATCH,
+ format!(
+ "{}/guilds/{}/members/@me",
+ user.belongs_to.read().unwrap().urls.api,
+ guild_id,
+ )
+ .as_str(),
+ Some(to_string(&schema).unwrap()),
+ audit_log_reason.as_deref(),
+ None,
+ Some(user),
+ LimitType::Guild(guild_id),
+ );
+ request.deserialize_response::(user).await
+ }
+
+ /// Modifies the current user's profile in the guild.
+ ///
+ /// # Reference:
+ /// See
+ pub async fn modify_current_member_profile(
+ guild_id: Snowflake,
+ schema: ModifyGuildMemberProfileSchema,
+ user: &mut ChorusUser,
+ ) -> ChorusResult {
+ let request = ChorusRequest::new(
+ http::Method::PATCH,
+ format!(
+ "{}/guilds/{}/profile/@me",
+ user.belongs_to.read().unwrap().urls.api,
+ guild_id,
+ )
+ .as_str(),
+ Some(to_string(&schema).unwrap()),
+ None,
+ None,
+ Some(user),
+ LimitType::Guild(guild_id),
+ );
+ request
+ .deserialize_response::(user)
+ .await
+ }
+
+ /// Returns a list of ban objects for the guild. Requires the `BAN_MEMBERS` permission.
+ ///
+ /// # Reference:
+ /// See
+ pub async fn get_bans(
+ user: &mut ChorusUser,
+ guild_id: Snowflake,
+ query: Option,
+ ) -> ChorusResult> {
+ let url = format!(
+ "{}/guilds/{}/bans",
+ user.belongs_to.read().unwrap().urls.api,
+ guild_id,
+ );
+
+ let mut request = ChorusRequest::new(
+ http::Method::GET,
+ &url,
+ None,
+ None,
+ None,
+ Some(user),
+ LimitType::Guild(guild_id),
+ );
+ if let Some(query) = query {
+ request.request = request.request.query(&to_string(&query).unwrap());
+ }
+ request.deserialize_response::>(user).await
+ }
+
+ /// Returns a ban object for the given user. Requires the `BAN_MEMBERS` permission.
+ ///
+ /// # Reference:
+ /// See
+ pub async fn get_ban(
+ user: &mut ChorusUser,
+ guild_id: Snowflake,
+ user_id: Snowflake,
+ ) -> ChorusResult {
+ let url = format!(
+ "{}/guilds/{}/bans/{}",
+ user.belongs_to.read().unwrap().urls.api,
+ guild_id,
+ user_id
+ );
+
+ let request = ChorusRequest::new(
+ http::Method::GET,
+ &url,
+ None,
+ None,
+ None,
+ Some(user),
+ LimitType::Guild(guild_id),
+ );
+ request.deserialize_response::(user).await
+ }
+
+ /// Removes the ban for a user. Requires the BAN_MEMBERS permissions. Returns a 204 empty response on success.
+ ///
+ /// # Reference:
+ /// See
+ pub async fn delete_ban(
+ user: &mut ChorusUser,
+ guild_id: Snowflake,
+ user_id: Snowflake,
+ audit_log_reason: Option,
+ ) -> ChorusResult<()> {
+ let url = format!(
+ "{}/guilds/{}/bans/{}",
+ user.belongs_to.read().unwrap().urls.api,
+ guild_id,
+ user_id
+ );
+
+ let request = ChorusRequest::new(
+ http::Method::DELETE,
+ &url,
+ None,
+ audit_log_reason.as_deref(),
+ None,
+ Some(user),
+ LimitType::Guild(guild_id),
+ );
+ request.handle_request_as_result(user).await
+ }
}
impl Channel {
- /// Sends a request to create a new channel in a guild.
+ /// Creates a new channel in a guild.
///
- /// # Arguments
+ /// Requires the [MANAGE_CHANNELS](crate::types::PermissionFlags::MANAGE_CHANNELS) permission.
///
- /// * `token` - A Discord bot token.
- /// * `url_api` - The base URL for the Discord API.
- /// * `guild_id` - The ID of the guild where the channel will be created.
- /// * `schema` - A `ChannelCreateSchema` struct containing the properties of the new channel.
- /// * `limits_user` - A mutable reference to a `Limits` struct containing the user's rate limits.
- /// * `limits_instance` - A mutable reference to a `Limits` struct containing the instance's rate limits.
- ///
- /// # Returns
- ///
- /// A `Result` containing a `reqwest::Response` if the request was successful, or an `ChorusLibError` if there was an error.
+ /// # Reference
+ /// See
pub async fn create(
- user: &mut UserMeta,
+ user: &mut ChorusUser,
guild_id: Snowflake,
+ audit_log_reason: Option,
schema: ChannelCreateSchema,
) -> ChorusResult {
+ let mut request = Client::new()
+ .post(format!(
+ "{}/guilds/{}/channels",
+ user.belongs_to.read().unwrap().urls.api,
+ guild_id
+ ))
+ .header("Authorization", user.token())
+ .header("Content-Type", "application/json")
+ .body(to_string(&schema).unwrap());
+ if let Some(reason) = audit_log_reason {
+ request = request.header("X-Audit-Log-Reason", reason);
+ }
let chorus_request = ChorusRequest {
- request: Client::new()
- .post(format!(
- "{}/guilds/{}/channels/",
- user.belongs_to.borrow().urls.api,
- guild_id
- ))
- .bearer_auth(user.token())
- .body(to_string(&schema).unwrap()),
+ request,
limit_type: LimitType::Guild(guild_id),
};
chorus_request.deserialize_response::(user).await
diff --git a/src/api/guilds/member.rs b/src/api/guilds/member.rs
index 5fa99cd..885ddf9 100644
--- a/src/api/guilds/member.rs
+++ b/src/api/guilds/member.rs
@@ -1,72 +1,61 @@
use reqwest::Client;
use crate::{
- api::LimitType,
errors::ChorusResult,
- instance::UserMeta,
+ instance::ChorusUser,
ratelimiter::ChorusRequest,
- types::{self, Snowflake},
+ types::{self, GuildMember, LimitType, Snowflake},
};
impl types::GuildMember {
- /// Retrieves a guild member by their ID.
+ /// Retrieves a guild member.
///
- /// # Arguments
- ///
- /// * `user` - A mutable reference to a [`UserMeta`] instance.
- /// * `guild_id` - The ID of the guild.
- /// * `member_id` - The ID of the member.
- ///
- /// # Returns
- ///
- /// A [`Result`] containing a [`GuildMember`] if the request succeeds, or a [`ChorusLibError`] if the request fails.
+ /// # Reference
+ /// See
pub async fn get(
- user: &mut UserMeta,
+ user: &mut ChorusUser,
guild_id: Snowflake,
member_id: Snowflake,
- ) -> ChorusResult {
+ ) -> ChorusResult {
let url = format!(
- "{}/guilds/{}/members/{}/",
- user.belongs_to.borrow().urls.api,
+ "{}/guilds/{}/members/{}",
+ user.belongs_to.read().unwrap().urls.api,
guild_id,
member_id
);
let chorus_request = ChorusRequest {
- request: Client::new().get(url).bearer_auth(user.token()),
+ request: Client::new().get(url).header("Authorization", user.token()),
limit_type: LimitType::Guild(guild_id),
};
chorus_request
- .deserialize_response::(user)
+ .deserialize_response::(user)
.await
}
/// Adds a role to a guild member.
///
- /// # Arguments
+ /// Requires the [`MANAGE_ROLES`](crate::types::PermissionFlags::MANAGE_ROLES) permission.
///
- /// * `user` - A mutable reference to a `UserMeta` instance.
- /// * `guild_id` - The ID of the guild.
- /// * `member_id` - The ID of the member.
- /// * `role_id` - The ID of the role to add.
- ///
- /// # Returns
- ///
- /// An `Result` containing a `ChorusLibError` if the request fails, or `()` if the request succeeds.
+ /// # Reference
+ /// See
pub async fn add_role(
- user: &mut UserMeta,
+ user: &mut ChorusUser,
guild_id: Snowflake,
member_id: Snowflake,
role_id: Snowflake,
) -> ChorusResult<()> {
let url = format!(
- "{}/guilds/{}/members/{}/roles/{}/",
- user.belongs_to.borrow().urls.api,
+ "{}/guilds/{}/members/{}/roles/{}",
+ user.belongs_to.read().unwrap().urls.api,
guild_id,
member_id,
role_id
);
let chorus_request = ChorusRequest {
- request: Client::new().put(url).bearer_auth(user.token()),
+ request: Client::new()
+ .put(url)
+ .header("Authorization", user.token())
+ .header("Content-Type", "application/json"),
limit_type: LimitType::Guild(guild_id),
};
chorus_request.handle_request_as_result(user).await
@@ -74,31 +63,27 @@ impl types::GuildMember {
/// Removes a role from a guild member.
///
- /// # Arguments
+ /// Requires the [`MANAGE_ROLES`](crate::types::PermissionFlags::MANAGE_ROLES) permission.
///
- /// * `user` - A mutable reference to a `UserMeta` instance.
- /// * `guild_id` - The ID of the guild.
- /// * `member_id` - The ID of the member.
- /// * `role_id` - The ID of the role to remove.
- ///
- /// # Returns
- ///
- /// A `Result` containing a `ChorusLibError` if the request fails, or `()` if the request succeeds.
+ /// # Reference
+ /// See
pub async fn remove_role(
- user: &mut UserMeta,
+ user: &mut ChorusUser,
guild_id: Snowflake,
member_id: Snowflake,
role_id: Snowflake,
) -> Result<(), crate::errors::ChorusError> {
let url = format!(
- "{}/guilds/{}/members/{}/roles/{}/",
- user.belongs_to.borrow().urls.api,
+ "{}/guilds/{}/members/{}/roles/{}",
+ user.belongs_to.read().unwrap().urls.api,
guild_id,
member_id,
role_id
);
let chorus_request = ChorusRequest {
- request: Client::new().delete(url).bearer_auth(user.token()),
+ request: Client::new()
+ .delete(url)
+ .header("Authorization", user.token()),
limit_type: LimitType::Guild(guild_id),
};
chorus_request.handle_request_as_result(user).await
diff --git a/src/api/guilds/messages.rs b/src/api/guilds/messages.rs
new file mode 100644
index 0000000..60fd4e3
--- /dev/null
+++ b/src/api/guilds/messages.rs
@@ -0,0 +1,28 @@
+use crate::errors::ChorusResult;
+use crate::instance::ChorusUser;
+use crate::types::{Guild, Message, MessageSearchQuery, Snowflake};
+
+impl Guild {
+ /// Returns messages without the reactions key that match a search query in the guild.
+ /// The messages that are direct results will have an extra hit key set to true.
+ /// If operating on a guild channel, this endpoint requires the `READ_MESSAGE_HISTORY`
+ /// permission to be present on the current user.
+ ///
+ /// If the guild/channel you are searching is not yet indexed, the endpoint will return a 202 accepted response.
+ /// In this case, the method will return a [`ChorusError::InvalidResponse`] error.
+ ///
+ /// # Reference:
+ /// See
+ pub async fn search_messages(
+ guild_id: Snowflake,
+ query: MessageSearchQuery,
+ user: &mut ChorusUser,
+ ) -> ChorusResult> {
+ Message::search(
+ crate::types::MessageSearchEndpoint::GuildChannel(guild_id),
+ query,
+ user,
+ )
+ .await
+ }
+}
diff --git a/src/api/guilds/mod.rs b/src/api/guilds/mod.rs
index 7577479..f1fa039 100644
--- a/src/api/guilds/mod.rs
+++ b/src/api/guilds/mod.rs
@@ -1,7 +1,9 @@
pub use guilds::*;
+pub use messages::*;
pub use roles::*;
pub use roles::*;
pub mod guilds;
pub mod member;
+pub mod messages;
pub mod roles;
diff --git a/src/api/guilds/roles.rs b/src/api/guilds/roles.rs
index 1d1bc68..f131367 100644
--- a/src/api/guilds/roles.rs
+++ b/src/api/guilds/roles.rs
@@ -2,79 +2,56 @@ use reqwest::Client;
use serde_json::to_string;
use crate::{
- api::LimitType,
errors::{ChorusError, ChorusResult},
- instance::UserMeta,
+ instance::ChorusUser,
ratelimiter::ChorusRequest,
- types::{self, RoleCreateModifySchema, RoleObject, Snowflake},
+ types::{
+ self, LimitType, RoleCreateModifySchema, RoleObject, RolePositionUpdateSchema, Snowflake,
+ },
};
impl types::RoleObject {
- /// Retrieves all roles for a given guild.
+ /// Retrieves a list of roles for a given guild.
///
- /// # Arguments
- ///
- /// * `user` - A mutable reference to a [`UserMeta`] instance.
- /// * `guild_id` - The ID of the guild to retrieve roles from.
- ///
- /// # Returns
- ///
- /// An `Option` containing a `Vec` of [`RoleObject`]s if roles were found, or `None` if no roles were found.
- ///
- /// # Errors
- ///
- /// Returns a [`ChorusLibError`] if the request fails or if the response is invalid.
+ /// # Reference
+ /// See
pub async fn get_all(
- user: &mut UserMeta,
+ user: &mut ChorusUser,
guild_id: Snowflake,
- ) -> ChorusResult>> {
+ ) -> ChorusResult> {
let url = format!(
- "{}/guilds/{}/roles/",
- user.belongs_to.borrow().urls.api,
+ "{}/guilds/{}/roles",
+ user.belongs_to.read().unwrap().urls.api,
guild_id
);
let chorus_request = ChorusRequest {
- request: Client::new().get(url).bearer_auth(user.token()),
+ request: Client::new().get(url).header("Authorization", user.token()),
limit_type: LimitType::Guild(guild_id),
};
let roles = chorus_request
.deserialize_response::>(user)
.await
.unwrap();
- if roles.is_empty() {
- return Ok(None);
- }
- Ok(Some(roles))
+ Ok(roles)
}
/// Retrieves a single role for a given guild.
///
- /// # Arguments
- ///
- /// * `user` - A mutable reference to a [`UserMeta`] instance.
- /// * `guild_id` - The ID of the guild to retrieve the role from.
- /// * `role_id` - The ID of the role to retrieve.
- ///
- /// # Returns
- ///
- /// A `Result` containing the retrieved [`RoleObject`] if successful, or a [`ChorusLibError`] if the request fails or if the response is invalid.
- ///
- /// # Errors
- ///
- /// Returns a [`ChorusLibError`] if the request fails or if the response is invalid.
+ /// # Reference
+ /// See
pub async fn get(
- user: &mut UserMeta,
+ user: &mut ChorusUser,
guild_id: Snowflake,
role_id: Snowflake,
) -> ChorusResult {
let url = format!(
- "{}/guilds/{}/roles/{}/",
- user.belongs_to.borrow().urls.api,
+ "{}/guilds/{}/roles/{}",
+ user.belongs_to.read().unwrap().urls.api,
guild_id,
role_id
);
let chorus_request = ChorusRequest {
- request: Client::new().get(url).bearer_auth(user.token()),
+ request: Client::new().get(url).header("Authorization", user.token()),
limit_type: LimitType::Guild(guild_id),
};
chorus_request
@@ -84,27 +61,18 @@ impl types::RoleObject {
/// Creates a new role for a given guild.
///
- /// # Arguments
+ /// Requires the [`MANAGE_ROLES`](crate::types::PermissionFlags::MANAGE_ROLES) permission.
///
- /// * `user` - A mutable reference to a [`UserMeta`] instance.
- /// * `guild_id` - The ID of the guild to create the role in.
- /// * `role_create_schema` - A [`RoleCreateModifySchema`] instance containing the properties of the role to be created.
- ///
- /// # Returns
- ///
- /// A `Result` containing the newly created [`RoleObject`] if successful, or a [`ChorusLibError`] if the request fails or if the response is invalid.
- ///
- /// # Errors
- ///
- /// Returns a [`ChorusLibError`] if the request fails or if the response is invalid.
+ /// # Reference
+ /// See
pub async fn create(
- user: &mut UserMeta,
+ user: &mut ChorusUser,
guild_id: Snowflake,
role_create_schema: RoleCreateModifySchema,
) -> ChorusResult {
let url = format!(
- "{}/guilds/{}/roles/",
- user.belongs_to.borrow().urls.api,
+ "{}/guilds/{}/roles",
+ user.belongs_to.read().unwrap().urls.api,
guild_id
);
let body = to_string::(&role_create_schema).map_err(|e| {
@@ -113,7 +81,11 @@ impl types::RoleObject {
}
})?;
let chorus_request = ChorusRequest {
- request: Client::new().post(url).bearer_auth(user.token()).body(body),
+ request: Client::new()
+ .post(url)
+ .header("Authorization", user.token())
+ .header("Content-Type", "application/json")
+ .body(body),
limit_type: LimitType::Guild(guild_id),
};
chorus_request
@@ -121,29 +93,20 @@ impl types::RoleObject {
.await
}
- /// Updates the position of a role in the guild's hierarchy.
+ /// Updates the position of a role in a given guild's hierarchy.
///
- /// # Arguments
+ /// Requires the [`MANAGE_ROLES`](crate::types::PermissionFlags::MANAGE_ROLES) permission.
///
- /// * `user` - A mutable reference to a [`UserMeta`] instance.
- /// * `guild_id` - The ID of the guild to update the role position in.
- /// * `role_position_update_schema` - A [`RolePositionUpdateSchema`] instance containing the new position of the role.
- ///
- /// # Returns
- ///
- /// A `Result` containing the updated [`RoleObject`] if successful, or a [`ChorusLibError`] if the request fails or if the response is invalid.
- ///
- /// # Errors
- ///
- /// Returns a [`ChorusLibError`] if the request fails or if the response is invalid.
+ /// # Reference
+ /// See
pub async fn position_update(
- user: &mut UserMeta,
+ user: &mut ChorusUser,
guild_id: Snowflake,
- role_position_update_schema: types::RolePositionUpdateSchema,
+ role_position_update_schema: RolePositionUpdateSchema,
) -> ChorusResult {
let url = format!(
- "{}/guilds/{}/roles/",
- user.belongs_to.borrow().urls.api,
+ "{}/guilds/{}/roles",
+ user.belongs_to.read().unwrap().urls.api,
guild_id
);
let body =
@@ -153,7 +116,8 @@ impl types::RoleObject {
let chorus_request = ChorusRequest {
request: Client::new()
.patch(url)
- .bearer_auth(user.token())
+ .header("Authorization", user.token())
+ .header("Content-Type", "application/json")
.body(body),
limit_type: LimitType::Guild(guild_id),
};
@@ -162,31 +126,21 @@ impl types::RoleObject {
.await
}
- /// Updates a role in a guild.
+ /// Modifies a role in a guild.
///
- /// # Arguments
+ /// Requires the [`MANAGE_ROLES`](crate::types::PermissionFlags::MANAGE_ROLES) permission.
///
- /// * `user` - A mutable reference to a [`UserMeta`] instance.
- /// * `guild_id` - The ID of the guild to update the role in.
- /// * `role_id` - The ID of the role to update.
- /// * `role_create_schema` - A [`RoleCreateModifySchema`] instance containing the new properties of the role.
- ///
- /// # Returns
- ///
- /// A `Result` containing the updated [`RoleObject`] if successful, or a [`ChorusLibError`] if the request fails or if the response is invalid.
- ///
- /// # Errors
- ///
- /// Returns a [`ChorusLibError`] if the request fails or if the response is invalid.
- pub async fn update(
- user: &mut UserMeta,
+ /// # Reference
+ /// See
+ pub async fn modify(
+ user: &mut ChorusUser,
guild_id: Snowflake,
role_id: Snowflake,
role_create_schema: RoleCreateModifySchema,
) -> ChorusResult {
let url = format!(
"{}/guilds/{}/roles/{}",
- user.belongs_to.borrow().urls.api,
+ user.belongs_to.read().unwrap().urls.api,
guild_id,
role_id
);
@@ -198,7 +152,8 @@ impl types::RoleObject {
let chorus_request = ChorusRequest {
request: Client::new()
.patch(url)
- .bearer_auth(user.token())
+ .header("Authorization", user.token())
+ .header("Content-Type", "application/json")
.body(body),
limit_type: LimitType::Guild(guild_id),
};
@@ -206,4 +161,33 @@ impl types::RoleObject {
.deserialize_response::(user)
.await
}
+
+ /// Deletes a guild role. Requires the `MANAGE_ROLES` permission. Returns a 204 empty response on success.
+ ///
+ /// # Reference:
+ /// See
+ pub async fn delete_role(
+ user: &mut ChorusUser,
+ guild_id: Snowflake,
+ role_id: Snowflake,
+ audit_log_reason: Option,
+ ) -> ChorusResult<()> {
+ let url = format!(
+ "{}/guilds/{}/roles/{}",
+ user.belongs_to.read().unwrap().urls.api,
+ guild_id,
+ role_id
+ );
+
+ let request = ChorusRequest::new(
+ http::Method::DELETE,
+ &url,
+ None,
+ audit_log_reason.as_deref(),
+ None,
+ Some(user),
+ LimitType::Guild(guild_id),
+ );
+ request.handle_request_as_result(user).await
+ }
}
diff --git a/src/api/invites/mod.rs b/src/api/invites/mod.rs
index b766a5b..332570b 100644
--- a/src/api/invites/mod.rs
+++ b/src/api/invites/mod.rs
@@ -2,17 +2,17 @@ use reqwest::Client;
use serde_json::to_string;
use crate::errors::ChorusResult;
-use crate::instance::UserMeta;
+use crate::instance::ChorusUser;
use crate::ratelimiter::ChorusRequest;
-use crate::types::{CreateChannelInviteSchema, GuildInvite, Invite, Snowflake};
+use crate::types::{CreateChannelInviteSchema, GuildInvite, Invite, LimitType, Snowflake};
-impl UserMeta {
- /// # Arguments
- /// - invite_code: The invite code to accept the invite for.
- /// - session_id: The session ID that is accepting the invite, required for guest invites.
+impl ChorusUser {
+ /// Accepts an invite to a guild, group DM, or DM.
+ ///
+ /// Note that the session ID is required for guest invites.
///
/// # Reference:
- /// Read
+ /// See
pub async fn accept_invite(
&mut self,
invite_code: &str,
@@ -21,37 +21,52 @@ impl UserMeta {
let mut request = ChorusRequest {
request: Client::new()
.post(format!(
- "{}/invites/{}/",
- self.belongs_to.borrow().urls.api,
+ "{}/invites/{}",
+ self.belongs_to.read().unwrap().urls.api,
invite_code
))
- .bearer_auth(self.token()),
- limit_type: super::LimitType::Global,
+ .header("Authorization", self.token()),
+ limit_type: LimitType::Global,
};
if session_id.is_some() {
request.request = request
.request
+ .header("Content-Type", "application/json")
.body(to_string(session_id.unwrap()).unwrap());
}
request.deserialize_response::(self).await
}
+
+ /// Creates a new friend invite.
+ ///
/// Note: Spacebar does not yet implement this endpoint.
+ ///
+ /// # Reference:
+ /// See
pub async fn create_user_invite(&mut self, code: Option<&str>) -> ChorusResult {
ChorusRequest {
request: Client::new()
.post(format!(
- "{}/users/@me/invites/",
- self.belongs_to.borrow().urls.api
+ "{}/users/@me/invites",
+ self.belongs_to.read().unwrap().urls.api
))
.body(to_string(&code).unwrap())
- .bearer_auth(self.token()),
- limit_type: super::LimitType::Global,
+ .header("Authorization", self.token())
+ .header("Content-Type", "application/json"),
+ limit_type: LimitType::Global,
}
.deserialize_response::(self)
.await
}
- pub async fn create_guild_invite(
+ /// Creates a new invite for a guild channel or group DM.
+ ///
+ /// # Guild Channels
+ /// For guild channels, the endpoint requires the [`CREATE_INSTANT_INVITE`](crate::types::PermissionFlags::CREATE_INSTANT_INVITE) permission.
+ ///
+ /// # Reference
+ /// See
+ pub async fn create_channel_invite(
&mut self,
create_channel_invite_schema: CreateChannelInviteSchema,
channel_id: Snowflake,
@@ -59,13 +74,14 @@ impl UserMeta {
ChorusRequest {
request: Client::new()
.post(format!(
- "{}/channels/{}/invites/",
- self.belongs_to.borrow().urls.api,
+ "{}/channels/{}/invites",
+ self.belongs_to.read().unwrap().urls.api,
channel_id
))
- .bearer_auth(self.token())
+ .header("Authorization", self.token())
+ .header("Content-Type", "application/json")
.body(to_string(&create_channel_invite_schema).unwrap()),
- limit_type: super::LimitType::Channel(channel_id),
+ limit_type: LimitType::Channel(channel_id),
}
.deserialize_response::(self)
.await
diff --git a/src/api/mod.rs b/src/api/mod.rs
index 9fd954d..ab3f9b9 100644
--- a/src/api/mod.rs
+++ b/src/api/mod.rs
@@ -1,8 +1,8 @@
+//! All of the API's endpoints.
pub use channels::messages::*;
pub use guilds::*;
pub use invites::*;
pub use policies::instance::instance::*;
-pub use policies::instance::ratelimits::*;
pub use users::*;
pub mod auth;
diff --git a/src/api/policies/instance/instance.rs b/src/api/policies/instance/instance.rs
index 75f832c..4de5fd8 100644
--- a/src/api/policies/instance/instance.rs
+++ b/src/api/policies/instance/instance.rs
@@ -6,16 +6,20 @@ use crate::types::GeneralConfiguration;
impl Instance {
/// Gets the instance policies schema.
- /// # Errors
- /// [`ChorusLibError`] - If the request fails.
+ ///
+ /// # Notes
+ /// This is a Spacebar only endpoint.
+ ///
+ /// # Reference
+ /// See
pub async fn general_configuration_schema(&self) -> ChorusResult {
- let endpoint_url = self.urls.api.clone() + "/policies/instance/";
+ let endpoint_url = self.urls.api.clone() + "/policies/instance";
let request = match self.client.get(&endpoint_url).send().await {
Ok(result) => result,
Err(e) => {
return Err(ChorusError::RequestFailed {
url: endpoint_url,
- error: e,
+ error: e.to_string(),
});
}
};
diff --git a/src/api/policies/instance/mod.rs b/src/api/policies/instance/mod.rs
index 0a1f245..b3a9148 100644
--- a/src/api/policies/instance/mod.rs
+++ b/src/api/policies/instance/mod.rs
@@ -1,5 +1,3 @@
pub use instance::*;
-pub use ratelimits::*;
pub mod instance;
-pub mod ratelimits;
diff --git a/src/api/policies/mod.rs b/src/api/policies/mod.rs
index d0c29f1..1d5ea99 100644
--- a/src/api/policies/mod.rs
+++ b/src/api/policies/mod.rs
@@ -1,3 +1 @@
-pub use instance::ratelimits::*;
-
pub mod instance;
diff --git a/src/api/users/channels.rs b/src/api/users/channels.rs
index 806bd9f..330b3e3 100644
--- a/src/api/users/channels.rs
+++ b/src/api/users/channels.rs
@@ -2,27 +2,33 @@ use reqwest::Client;
use serde_json::to_string;
use crate::{
- api::LimitType,
errors::ChorusResult,
- instance::UserMeta,
+ instance::ChorusUser,
ratelimiter::ChorusRequest,
- types::{Channel, PrivateChannelCreateSchema},
+ types::{Channel, LimitType, PrivateChannelCreateSchema},
};
-impl UserMeta {
+impl ChorusUser {
/// Creates a DM channel or group DM channel.
///
+ /// One recipient creates or returns an existing DM channel,
+ /// none or multiple recipients create a group DM channel.
+ ///
/// # Reference:
- /// Read
+ /// See
pub async fn create_private_channel(
&mut self,
create_private_channel_schema: PrivateChannelCreateSchema,
) -> ChorusResult {
- let url = format!("{}/users/@me/channels", self.belongs_to.borrow().urls.api);
+ let url = format!(
+ "{}/users/@me/channels",
+ self.belongs_to.read().unwrap().urls.api
+ );
ChorusRequest {
request: Client::new()
.post(url)
- .bearer_auth(self.token())
+ .header("Authorization", self.token())
+ .header("Content-Type", "application/json")
.body(to_string(&create_private_channel_schema).unwrap()),
limit_type: LimitType::Global,
}
diff --git a/src/api/users/guilds.rs b/src/api/users/guilds.rs
index 735ed9e..6ffcdfc 100644
--- a/src/api/users/guilds.rs
+++ b/src/api/users/guilds.rs
@@ -2,29 +2,59 @@ use reqwest::Client;
use serde_json::to_string;
use crate::errors::ChorusResult;
-use crate::instance::UserMeta;
+use crate::instance::ChorusUser;
use crate::ratelimiter::ChorusRequest;
-use crate::types::Snowflake;
+use crate::types::{GetUserGuildSchema, Guild, LimitType, Snowflake};
-impl UserMeta {
- /// # Arguments:
- /// - lurking: Whether the user is lurking in the guild
+impl ChorusUser {
+ /// Leaves a given guild.
///
/// # Reference:
- /// Read
+ /// See
+ // TODO: Docs: What is "lurking" here?
+ // It is documented as "Whether the user is lurking in the guild",
+ // but that says nothing about what this field actually does / means
pub async fn leave_guild(&mut self, guild_id: &Snowflake, lurking: bool) -> ChorusResult<()> {
ChorusRequest {
request: Client::new()
.delete(format!(
- "{}/users/@me/guilds/{}/",
- self.belongs_to.borrow().urls.api,
+ "{}/users/@me/guilds/{}",
+ self.belongs_to.read().unwrap().urls.api,
guild_id
))
- .bearer_auth(self.token())
+ .header("Authorization", self.token())
+ .header("Content-Type", "application/json")
.body(to_string(&lurking).unwrap()),
- limit_type: crate::api::LimitType::Guild(*guild_id),
+ limit_type: LimitType::Guild(*guild_id),
}
.handle_request_as_result(self)
.await
}
+
+ /// Returns a list of user guild objects representing the guilds the current user is a member of.
+ /// This endpoint returns 200 guilds by default
+ ///
+ /// # Reference:
+ /// See:
+ pub async fn get_guilds(
+ &mut self,
+ query: Option,
+ ) -> ChorusResult> {
+ let url = format!(
+ "{}/users/@me/guilds",
+ self.belongs_to.read().unwrap().urls.api,
+ );
+ let chorus_request = ChorusRequest {
+ request: Client::new()
+ .get(url)
+ .header("Authorization", self.token())
+ .header("Content-Type", "application/json")
+ .body(to_string(&query).unwrap()),
+
+ limit_type: LimitType::Global,
+ };
+ chorus_request
+ .deserialize_response::>(self)
+ .await
+ }
}
diff --git a/src/api/users/relationships.rs b/src/api/users/relationships.rs
index 39c75d8..4f9602c 100644
--- a/src/api/users/relationships.rs
+++ b/src/api/users/relationships.rs
@@ -2,33 +2,31 @@ use reqwest::Client;
use serde_json::to_string;
use crate::{
- api::LimitType,
errors::ChorusResult,
- instance::UserMeta,
+ instance::ChorusUser,
ratelimiter::ChorusRequest,
- types::{self, CreateUserRelationshipSchema, RelationshipType, Snowflake},
+ types::{
+ self, CreateUserRelationshipSchema, FriendRequestSendSchema, LimitType, RelationshipType,
+ Snowflake,
+ },
};
-impl UserMeta {
- /// Retrieves the mutual relationships between the authenticated user and the specified user.
+impl ChorusUser {
+ /// Retrieves a list of mutual friends between the authenticated user and a given user.
///
- /// # Arguments
- ///
- /// * `user_id` - ID of the user to retrieve the mutual relationships with.
- ///
- /// # Returns
- /// This function returns a [`ChorusResult>`].
+ /// # Reference
+ /// See
pub async fn get_mutual_relationships(
&mut self,
user_id: Snowflake,
) -> ChorusResult> {
let url = format!(
- "{}/users/{}/relationships/",
- self.belongs_to.borrow().urls.api,
+ "{}/users/{}/relationships",
+ self.belongs_to.read().unwrap().urls.api,
user_id
);
let chorus_request = ChorusRequest {
- request: Client::new().get(url).bearer_auth(self.token()),
+ request: Client::new().get(url).header("Authorization", self.token()),
limit_type: LimitType::Global,
};
chorus_request
@@ -36,17 +34,17 @@ impl UserMeta {
.await
}
- /// Retrieves the authenticated user's relationships.
+ /// Retrieves the user's relationships.
///
- /// # Returns
- /// This function returns a [`ChorusResult>`].
+ /// # Reference
+ /// See
pub async fn get_relationships(&mut self) -> ChorusResult> {
let url = format!(
- "{}/users/@me/relationships/",
- self.belongs_to.borrow().urls.api
+ "{}/users/@me/relationships",
+ self.belongs_to.read().unwrap().urls.api
);
let chorus_request = ChorusRequest {
- request: Client::new().get(url).bearer_auth(self.token()),
+ request: Client::new().get(url).header("Authorization", self.token()),
limit_type: LimitType::Global,
};
chorus_request
@@ -56,54 +54,43 @@ impl UserMeta {
/// Sends a friend request to a user.
///
- /// # Arguments
- ///
- /// * `schema` - A [`FriendRequestSendSchema`] struct that holds the information about the friend request to be sent.
- ///
- /// # Returns
- /// This function returns a [`Result`] that holds a [`ChorusLibError`] if the request fails.
+ /// # Reference
+ /// See
pub async fn send_friend_request(
&mut self,
- schema: types::FriendRequestSendSchema,
+ schema: FriendRequestSendSchema,
) -> ChorusResult<()> {
let url = format!(
- "{}/users/@me/relationships/",
- self.belongs_to.borrow().urls.api
+ "{}/users/@me/relationships",
+ self.belongs_to.read().unwrap().urls.api
);
let body = to_string(&schema).unwrap();
let chorus_request = ChorusRequest {
- request: Client::new().post(url).bearer_auth(self.token()).body(body),
+ request: Client::new()
+ .post(url)
+ .header("Authorization", self.token())
+ .header("Content-Type", "application/json")
+ .body(body),
limit_type: LimitType::Global,
};
chorus_request.handle_request_as_result(self).await
}
- /// Modifies the relationship between the authenticated user and the specified user.
+ /// Modifies the relationship between the authenticated user and a given user.
///
- /// # Arguments
- ///
- /// * `user_id` - ID of the user to modify the relationship with.
- /// * `relationship_type` - A [`RelationshipType`] enum that specifies the type of relationship to modify.
- /// * [`RelationshipType::None`]: Removes the relationship between the two users.
- /// * [`RelationshipType::Friends`] | [`RelationshipType::Incoming`] | [`RelationshipType::Outgoing`]:
- /// Either accepts an incoming friend request, or sends a new friend request, if there is no
- /// incoming friend request from the specified `user_id`.
- /// * [`RelationshipType::Blocked`]: Blocks the specified user_id.
- ///
- /// # Returns
- /// This function returns an [`Result`] that holds a [`ChorusLibError`] if the request fails.
+ /// Can be used to unfriend users, accept or send friend requests and block or unblock users.
pub async fn modify_user_relationship(
&mut self,
user_id: Snowflake,
relationship_type: RelationshipType,
) -> ChorusResult<()> {
- let api_url = self.belongs_to.borrow().urls.api.clone();
+ let api_url = self.belongs_to.read().unwrap().urls.api.clone();
match relationship_type {
RelationshipType::None => {
let chorus_request = ChorusRequest {
request: Client::new()
- .delete(format!("{}/users/@me/relationships/{}/", api_url, user_id))
- .bearer_auth(self.token()),
+ .delete(format!("{}/users/@me/relationships/{}", api_url, user_id))
+ .header("Authorization", self.token()),
limit_type: LimitType::Global,
};
chorus_request.handle_request_as_result(self).await
@@ -116,8 +103,8 @@ impl UserMeta {
};
let chorus_request = ChorusRequest {
request: Client::new()
- .put(format!("{}/users/@me/relationships/{}/", api_url, user_id))
- .bearer_auth(self.token())
+ .put(format!("{}/users/@me/relationships/{}", api_url, user_id))
+ .header("Authorization", self.token())
.body(to_string(&body).unwrap()),
limit_type: LimitType::Global,
};
@@ -131,8 +118,8 @@ impl UserMeta {
};
let chorus_request = ChorusRequest {
request: Client::new()
- .put(format!("{}/users/@me/relationships/{}/", api_url, user_id))
- .bearer_auth(self.token())
+ .put(format!("{}/users/@me/relationships/{}", api_url, user_id))
+ .header("Authorization", self.token())
.body(to_string(&body).unwrap()),
limit_type: LimitType::Global,
};
@@ -142,22 +129,20 @@ impl UserMeta {
}
}
- /// Removes the relationship between the authenticated user and the specified user.
+ /// Removes the relationship between the authenticated user and a given user.
///
- /// # Arguments
- ///
- /// * `user_id` - ID of the user to remove the relationship with.
- ///
- /// # Returns
- /// This function returns a [`Result`] that holds a [`ChorusLibError`] if the request fails.
+ /// # Reference
+ /// See
pub async fn remove_relationship(&mut self, user_id: Snowflake) -> ChorusResult<()> {
let url = format!(
- "{}/users/@me/relationships/{}/",
- self.belongs_to.borrow().urls.api,
+ "{}/users/@me/relationships/{}",
+ self.belongs_to.read().unwrap().urls.api,
user_id
);
let chorus_request = ChorusRequest {
- request: Client::new().delete(url).bearer_auth(self.token()),
+ request: Client::new()
+ .delete(url)
+ .header("Authorization", self.token()),
limit_type: LimitType::Global,
};
chorus_request.handle_request_as_result(self).await
diff --git a/src/api/users/users.rs b/src/api/users/users.rs
index af6d2ce..0f31d6f 100644
--- a/src/api/users/users.rs
+++ b/src/api/users/users.rs
@@ -1,33 +1,32 @@
-use std::{cell::RefCell, rc::Rc};
+use std::sync::{Arc, RwLock};
use reqwest::Client;
use serde_json::to_string;
use crate::{
- api::LimitType,
errors::{ChorusError, ChorusResult},
- instance::{Instance, UserMeta},
+ instance::{ChorusUser, Instance},
ratelimiter::ChorusRequest,
- types::{User, UserModifySchema, UserSettings},
+ types::{LimitType, User, UserModifySchema, UserSettings},
};
-impl UserMeta {
- /// Get a user object by id, or get the current user.
+impl ChorusUser {
+ /// Gets a user by id, or if the id is None, gets the current user.
///
- /// # Arguments
+ /// # Notes
+ /// This function is a wrapper around [`User::get`].
///
- /// * `token` - A valid access token for the API.
- /// * `url_api` - The URL to the API.
- /// * `id` - The id of the user that will be retrieved. If this is None, the current user will be retrieved.
- /// * `instance_limits` - The [`Limits`] of the instance.
- ///
- /// # Errors
- ///
- /// * [`ChorusLibError`] - If the request fails.
- pub async fn get(user: &mut UserMeta, id: Option<&String>) -> ChorusResult {
- User::get(user, id).await
+ /// # Reference
+ /// See and
+ ///
+ pub async fn get_user(&mut self, id: Option<&String>) -> ChorusResult {
+ User::get(self, id).await
}
+ /// Gets the user's settings.
+ ///
+ /// # Notes
+ /// This functions is a wrapper around [`User::get_settings`].
pub async fn get_settings(
token: &String,
url_api: &String,
@@ -36,15 +35,10 @@ impl UserMeta {
User::get_settings(token, url_api, instance).await
}
- /// Modify the current user's `UserObject`.
+ /// Modifies the current user's representation. (See [`User`])
///
- /// # Arguments
- ///
- /// * `modify_schema` - A `UserModifySchema` object containing the fields to modify.
- ///
- /// # Errors
- ///
- /// Returns an `ChorusLibError` if the request fails or if a password is required but not provided.
+ /// # Reference
+ /// See
pub async fn modify(&mut self, modify_schema: UserModifySchema) -> ChorusResult {
if modify_schema.new_password.is_some()
|| modify_schema.email.is_some()
@@ -53,37 +47,32 @@ impl UserMeta {
return Err(ChorusError::PasswordRequired);
}
let request = Client::new()
- .patch(format!("{}/users/@me/", self.belongs_to.borrow().urls.api))
+ .patch(format!(
+ "{}/users/@me",
+ self.belongs_to.read().unwrap().urls.api
+ ))
.body(to_string(&modify_schema).unwrap())
- .bearer_auth(self.token());
+ .header("Authorization", self.token())
+ .header("Content-Type", "application/json");
let chorus_request = ChorusRequest {
request,
limit_type: LimitType::default(),
};
- let user_updated = chorus_request
- .deserialize_response::(self)
- .await
- .unwrap();
- let _ = std::mem::replace(&mut self.object, user_updated.clone());
- Ok(user_updated)
+ chorus_request.deserialize_response::(self).await
}
- /// Sends a request to the server which deletes the user from the Instance.
+ /// Deletes the user from the Instance.
///
- /// # Arguments
- ///
- /// * `self` - The `User` object to delete.
- ///
- /// # Returns
- ///
- /// Returns `()` if the user was successfully deleted, or a `ChorusLibError` if an error occurred.
+ /// # Reference
+ /// See
pub async fn delete(mut self) -> ChorusResult<()> {
let request = Client::new()
.post(format!(
- "{}/users/@me/delete/",
- self.belongs_to.borrow().urls.api
+ "{}/users/@me/delete",
+ self.belongs_to.read().unwrap().urls.api
))
- .bearer_auth(self.token());
+ .header("Authorization", self.token())
+ .header("Content-Type", "application/json");
let chorus_request = ChorusRequest {
request,
limit_type: LimitType::default(),
@@ -93,14 +82,21 @@ impl UserMeta {
}
impl User {
- pub async fn get(user: &mut UserMeta, id: Option<&String>) -> ChorusResult {
- let url_api = user.belongs_to.borrow().urls.api.clone();
+ /// Gets a user by id, or if the id is None, gets the current user.
+ ///
+ /// # Reference
+ /// See and
+ ///
+ pub async fn get(user: &mut ChorusUser, id: Option<&String>) -> ChorusResult {
+ let url_api = user.belongs_to.read().unwrap().urls.api.clone();
let url = if id.is_none() {
- format!("{}/users/@me/", url_api)
+ format!("{}/users/@me", url_api)
} else {
format!("{}/users/{}", url_api, id.unwrap())
};
- let request = reqwest::Client::new().get(url).bearer_auth(user.token());
+ let request = reqwest::Client::new()
+ .get(url)
+ .header("Authorization", user.token());
let chorus_request = ChorusRequest {
request,
limit_type: LimitType::Global,
@@ -114,16 +110,20 @@ impl User {
}
}
+ /// Gets the user's settings.
+ ///
+ /// # Reference
+ /// See
pub async fn get_settings(
token: &String,
url_api: &String,
instance: &mut Instance,
) -> ChorusResult {
let request: reqwest::RequestBuilder = Client::new()
- .get(format!("{}/users/@me/settings/", url_api))
- .bearer_auth(token);
+ .get(format!("{}/users/@me/settings", url_api))
+ .header("Authorization", token);
let mut user =
- UserMeta::shell(Rc::new(RefCell::new(instance.clone())), token.clone()).await;
+ ChorusUser::shell(Arc::new(RwLock::new(instance.clone())), token.clone()).await;
let chorus_request = ChorusRequest {
request,
limit_type: LimitType::Global,
@@ -133,30 +133,36 @@ impl User {
Err(e) => Err(e),
};
if instance.limits_information.is_some() {
- instance.limits_information.as_mut().unwrap().ratelimits =
- user.belongs_to.borrow().clone_limits_if_some().unwrap();
+ instance.limits_information.as_mut().unwrap().ratelimits = user
+ .belongs_to
+ .read()
+ .unwrap()
+ .clone_limits_if_some()
+ .unwrap();
}
result
}
}
impl Instance {
- /**
- Get a user object by id, or get the current user.
- # Arguments
- * `token` - A valid access token for the API.
- * `id` - The id of the user that will be retrieved. If this is None, the current user will be retrieved.
- # Errors
- * [`ChorusLibError`] - If the request fails.
- # Notes
- This function is a wrapper around [`User::get`].
- */
+ /// Gets a user by id, or if the id is None, gets the current user.
+ ///
+ /// # Notes
+ /// This function is a wrapper around [`User::get`].
+ ///
+ /// # Reference
+ /// See and
+ ///
pub async fn get_user(&mut self, token: String, id: Option<&String>) -> ChorusResult {
- let mut user = UserMeta::shell(Rc::new(RefCell::new(self.clone())), token).await;
+ let mut user = ChorusUser::shell(Arc::new(RwLock::new(self.clone())), token).await;
let result = User::get(&mut user, id).await;
if self.limits_information.is_some() {
- self.limits_information.as_mut().unwrap().ratelimits =
- user.belongs_to.borrow().clone_limits_if_some().unwrap();
+ self.limits_information.as_mut().unwrap().ratelimits = user
+ .belongs_to
+ .read()
+ .unwrap()
+ .clone_limits_if_some()
+ .unwrap();
}
result
}
diff --git a/src/errors.rs b/src/errors.rs
index 0a962b1..4a251c9 100644
--- a/src/errors.rs
+++ b/src/errors.rs
@@ -1,8 +1,10 @@
+//! Contains all the errors that can be returned by the library.
use custom_error::custom_error;
-use reqwest::Error;
+
+use crate::types::WebSocketEvent;
custom_error! {
- #[derive(PartialEq, Eq)]
+ #[derive(PartialEq, Eq, Clone, Hash)]
pub RegistrationError
Consent = "Consent must be 'true' to register.",
}
@@ -10,11 +12,12 @@ custom_error! {
pub type ChorusResult = std::result::Result;
custom_error! {
+ #[derive(Clone, Hash, PartialEq, Eq)]
pub ChorusError
/// Server did not respond.
NoResponse = "Did not receive a response from the Server.",
/// Reqwest returned an Error instead of a Response object.
- RequestFailed{url:String, error: Error} = "An error occured while trying to GET from {url}: {error}",
+ RequestFailed{url:String, error: String} = "An error occured while trying to GET from {url}: {error}",
/// Response received, however, it was not of the successful responses type. Used when no other, special case applies.
ReceivedErrorCode{error_code: u16, error: String} = "Received the following error code while requesting from the route: {error_code}",
/// Used when there is likely something wrong with the instance, the request was directed to.
@@ -53,9 +56,10 @@ custom_error! {
/// Supposed to be sent as numbers, though they are sent as string most of the time?
///
/// Also includes errors when initiating a connection and unexpected opcodes
- #[derive(Clone, PartialEq, Eq)]
+ #[derive(PartialEq, Eq, Default, Clone)]
pub GatewayError
// Errors we have received from the gateway
+ #[default]
Unknown = "We're not sure what went wrong. Try reconnecting?",
UnknownOpcode = "You sent an invalid Gateway opcode or an invalid payload for an opcode",
Decode = "Gateway server couldn't decode payload",
@@ -79,25 +83,29 @@ custom_error! {
UnexpectedOpcodeReceived{opcode: u8} = "Received an opcode we weren't expecting to receive: {opcode}",
}
+impl WebSocketEvent for GatewayError {}
+
custom_error! {
- // Like GatewayError for webrtc errors
- // See https://discord.com/developers/docs/topics/opcodes-and-status-codes#voice;
- // Also supposed to be sent by numbers, but discord is asdfghgfjkkjldf when it comes to their errors
+ /// Voice Gateway errors
+ ///
+ /// Similar to [GatewayError].
+ ///
+ /// See https://discord.com/developers/docs/topics/opcodes-and-status-codes#voice;
#[derive(Clone, PartialEq, Eq)]
pub VoiceGatewayError
// Errors we receive
- UnknownOpcodeError = "You sent an invalid opcode",
- FailedToDecodePayloadError = "You sent an invalid payload in your identifying to the (Webrtc) Gateway",
- NotAuthenticatedError = "You sent a payload before identifying with the (Webrtc) Gateway",
- AuthenticationFailedError = "The token you sent in your identify payload is incorrect",
- AlreadyAuthenticatedError = "You sent more than one identify payload",
- SessionNoLongerValidError = "Your session is no longer valid",
- SessionTimeoutError = "Your session has timed out",
- ServerNotFoundError = "We can't find the server you're trying to connect to",
- UnknownProtocolError = "We didn't recognize the protocol you sent",
- DisconnectedError = "Channel was deleted, you were kicked, voice server changed, or the main gateway session was dropped. Should not reconnect.",
- VoiceServerCrashedError = "The server crashed, try resuming",
- UnknownEncryptionModeError = "Server failed to decrypt data",
+ UnknownOpcode = "You sent an invalid opcode",
+ FailedToDecodePayload = "You sent an invalid payload in your identifying to the (Webrtc) Gateway",
+ NotAuthenticated = "You sent a payload before identifying with the (Webrtc) Gateway",
+ AuthenticationFailed = "The token you sent in your identify payload is incorrect",
+ AlreadyAuthenticated = "You sent more than one identify payload",
+ SessionNoLongerValid = "Your session is no longer valid",
+ SessionTimeout = "Your session has timed out",
+ ServerNotFound = "We can't find the server you're trying to connect to",
+ UnknownProtocol = "We didn't recognize the protocol you sent",
+ Disconnected = "Channel was deleted, you were kicked, voice server changed, or the main gateway session was dropped. Should not reconnect.",
+ VoiceServerCrashed = "The server crashed, try resuming",
+ UnknownEncryptionMode = "Server failed to decrypt data",
// Errors when initiating a gateway connection
CannotConnect{error: String} = "Cannot connect due to a tungstenite error: {error}",
diff --git a/src/gateway.rs b/src/gateway.rs
index 8e60dd0..def0df1 100644
--- a/src/gateway.rs
+++ b/src/gateway.rs
@@ -1,14 +1,18 @@
+//! Gateway connection, communication and handling, as well as object caching and updating.
+
use crate::errors::GatewayError;
use crate::gateway::events::Events;
-use crate::types::{self, Channel, ChannelUpdate, Snowflake};
-use crate::types::{UpdateMessage, WebSocketEvent};
+use crate::types::{
+ self, AutoModerationRule, AutoModerationRuleUpdate, Channel, ChannelCreate, ChannelDelete,
+ ChannelUpdate, Composite, Guild, GuildRoleCreate, GuildRoleUpdate, JsonField, RoleObject,
+ Snowflake, SourceUrlField, ThreadUpdate, UpdateMessage, WebSocketEvent,
+};
use async_trait::async_trait;
use std::any::Any;
use std::collections::HashMap;
use std::fmt::Debug;
-use std::sync::Arc;
+use std::sync::{Arc, RwLock};
use std::time::Duration;
-use tokio::sync::watch;
use tokio::time::sleep_until;
use futures_util::stream::SplitSink;
@@ -78,7 +82,7 @@ const GATEWAY_LAZY_REQUEST: u8 = 14;
/// The amount of time we wait for a heartbeat ack before resending our heartbeat in ms
pub(crate) const HEARTBEAT_ACK_TIMEOUT: u64 = 2000;
-/// Represents a messsage received from the gateway. This will be either a [GatewayReceivePayload], containing events, or a [GatewayError].
+/// Represents a messsage received from the gateway. This will be either a [types::GatewayReceivePayload], containing events, or a [GatewayError].
/// This struct is used internally when handling messages.
#[derive(Clone, Debug)]
pub struct GatewayMessage {
@@ -148,11 +152,13 @@ impl GatewayMessage {
}
}
+pub type ObservableObject = dyn Send + Sync + Any;
+
/// Represents a handle to a Gateway connection. A Gateway connection will create observable
/// [`GatewayEvents`](GatewayEvent), which you can subscribe to. Gateway events include all currently
-/// implemented [Types] with the trait [`WebSocketEvent`]
+/// implemented types with the trait [`WebSocketEvent`]
/// Using this handle you can also send Gateway Events directly.
-#[derive(Debug)]
+#[derive(Debug, Clone)]
pub struct GatewayHandle {
pub url: String,
pub events: Arc>,
@@ -164,10 +170,9 @@ pub struct GatewayHandle {
>,
>,
>,
- pub handle: JoinHandle<()>,
/// Tells gateway tasks to close
kill_send: tokio::sync::broadcast::Sender<()>,
- store: Arc>>>,
+ pub(crate) store: Arc>>>>,
}
/// An entity type which is supposed to be updateable via the Gateway. This is implemented for all such types chorus supports, implementing it for your own types is likely a mistake.
@@ -196,27 +201,57 @@ impl GatewayHandle {
.unwrap();
}
- pub async fn observe(&self, object: T) -> watch::Receiver {
+ pub async fn observe>(
+ &self,
+ object: Arc>,
+ ) -> Arc> {
let mut store = self.store.lock().await;
- if let Some(channel) = store.get(&object.id()) {
- let (_, rx) = channel
- .downcast_ref::<(watch::Sender, watch::Receiver)>()
+ let id = object.read().unwrap().id();
+ if let Some(channel) = store.get(&id) {
+ let object = channel.clone();
+ drop(store);
+ object
+ .read()
+ .unwrap()
+ .downcast_ref::()
.unwrap_or_else(|| {
panic!(
"Snowflake {} already exists in the store, but it is not of type T.",
- object.id()
+ id
)
});
- rx.clone()
+ let ptr = Arc::into_raw(object.clone());
+ // SAFETY:
+ // - We have just checked that the typeid of the `dyn Any ...` matches that of `T`.
+ // - This operation doesn't read or write any shared data, and thus cannot cause a data race
+ // - The reference count is not being modified
+ let downcasted = unsafe { Arc::from_raw(ptr as *const RwLock).clone() };
+ let object = downcasted.read().unwrap().clone();
+
+ let watched_object = object.watch_whole(self).await;
+ *downcasted.write().unwrap() = watched_object;
+ downcasted
} else {
- let id = object.id();
- let channel = watch::channel(object);
- let receiver = channel.1.clone();
- store.insert(id, Box::new(channel));
- receiver
+ let id = object.read().unwrap().id();
+ let object = object.read().unwrap().clone();
+ let object = object.clone().watch_whole(self).await;
+ let wrapped = Arc::new(RwLock::new(object));
+ store.insert(id, wrapped.clone());
+ wrapped
}
}
+ /// Recursively observes and updates all updateable fields on the struct T. Returns an object `T`
+ /// with all of its observable fields being observed.
+ pub async fn observe_and_into_inner>(
+ &self,
+ object: Arc>,
+ ) -> T {
+ let channel = self.observe(object.clone()).await;
+ let object = channel.read().unwrap().clone();
+ object
+ }
+
/// Sends an identify event to the gateway
pub async fn send_identify(&self, to_send: types::GatewayIdentifyPayload) {
let to_send_value = serde_json::to_value(&to_send).unwrap();
@@ -257,7 +292,7 @@ impl GatewayHandle {
/// Sends an update voice state to the server
pub async fn send_update_voice_state(&self, to_send: types::UpdateVoiceState) {
- let to_send_value = serde_json::to_value(&to_send).unwrap();
+ let to_send_value = serde_json::to_value(to_send).unwrap();
trace!("GW: Sending Update Voice State..");
@@ -293,6 +328,7 @@ impl GatewayHandle {
}
}
+#[derive(Debug)]
pub struct Gateway {
events: Arc>,
heartbeat_handler: HeartbeatHandler,
@@ -306,7 +342,8 @@ pub struct Gateway {
>,
websocket_receive: SplitStream>>,
kill_send: tokio::sync::broadcast::Sender<()>,
- store: Arc>>>,
+ store: Arc>>>>,
+ url: String,
}
impl Gateway {
@@ -370,10 +407,11 @@ impl Gateway {
websocket_receive,
kill_send: kill_send.clone(),
store: store.clone(),
+ url: websocket_url.clone(),
};
// Now we can continuously check for messages in a different task, since we aren't going to receive another hello
- let handle: JoinHandle<()> = task::spawn(async move {
+ task::spawn(async move {
gateway.gateway_listen_task().await;
});
@@ -381,7 +419,6 @@ impl Gateway {
url: websocket_url.clone(),
events: shared_events,
websocket_send: shared_websocket_send.clone(),
- handle,
kill_send: kill_send.clone(),
store,
})
@@ -444,13 +481,15 @@ impl Gateway {
return;
}
- // Todo: handle errors in a good way, maybe observers like events?
if msg.is_error() {
- warn!("GW: Received error, connection will close..");
+ let error = msg.error().unwrap();
- let _error = msg.error();
+ warn!("GW: Received error {:?}, connection will close..", error);
self.close().await;
+
+ self.events.lock().await.error.notify(error).await;
+
return;
}
@@ -462,7 +501,7 @@ impl Gateway {
GATEWAY_DISPATCH => {
let Some(event_name) = gateway_payload.event_name else {
warn!("Gateway dispatch op without event_name");
- return
+ return;
};
trace!("Gateway: Received {event_name}");
@@ -472,16 +511,35 @@ impl Gateway {
match event_name.as_str() {
$($name => {
let event = &mut self.events.lock().await.$($path).+;
- match serde_json::from_str(gateway_payload.event_data.unwrap().get()) {
+ let json = gateway_payload.event_data.unwrap().get();
+ match serde_json::from_str(json) {
Err(err) => warn!("Failed to parse gateway event {event_name} ({err})"),
Ok(message) => {
$(
- let message: $message_type = message;
- if let Some(to_update) = self.store.lock().await.get(&message.id()) {
- if let Some((tx, _)) = to_update.downcast_ref::<(watch::Sender<$update_type>, watch::Receiver<$update_type>)>() {
- tx.send_modify(|object| message.update(object));
+ let mut message: $message_type = message;
+ let store = self.store.lock().await;
+ let id = if message.id().is_some() {
+ message.id().unwrap()
+ } else {
+ event.notify(message).await;
+ return;
+ };
+ if let Some(to_update) = store.get(&id) {
+ let object = to_update.clone();
+ let inner_object = object.read().unwrap();
+ if let Some(_) = inner_object.downcast_ref::<$update_type>() {
+ let ptr = Arc::into_raw(object.clone());
+ // SAFETY:
+ // - We have just checked that the typeid of the `dyn Any ...` matches that of `T`.
+ // - This operation doesn't read or write any shared data, and thus cannot cause a data race
+ // - The reference count is not being modified
+ let downcasted = unsafe { Arc::from_raw(ptr as *const RwLock<$update_type>).clone() };
+ drop(inner_object);
+ message.set_json(json.to_string());
+ message.set_source_url(self.url.clone());
+ message.update(downcasted.clone());
} else {
- warn!("Received {} for {}, but it has been observed to be a different type!", $name, message.id())
+ warn!("Received {} for {}, but it has been observed to be a different type!", $name, id)
}
}
)?
@@ -523,69 +581,70 @@ impl Gateway {
"READY_SUPPLEMENTAL" => session.ready_supplemental,
"APPLICATION_COMMAND_PERMISSIONS_UPDATE" => application.command_permissions_update,
"AUTO_MODERATION_RULE_CREATE" =>auto_moderation.rule_create,
- "AUTO_MODERATION_RULE_UPDATE" =>auto_moderation.rule_update,
+ "AUTO_MODERATION_RULE_UPDATE" =>auto_moderation.rule_update AutoModerationRuleUpdate: AutoModerationRule,
"AUTO_MODERATION_RULE_DELETE" => auto_moderation.rule_delete,
"AUTO_MODERATION_ACTION_EXECUTION" => auto_moderation.action_execution,
- "CHANNEL_CREATE" => channel.create,
+ "CHANNEL_CREATE" => channel.create ChannelCreate: Guild,
"CHANNEL_UPDATE" => channel.update ChannelUpdate: Channel,
"CHANNEL_UNREAD_UPDATE" => channel.unread_update,
- "CHANNEL_DELETE" => channel.delete,
+ "CHANNEL_DELETE" => channel.delete ChannelDelete: Guild,
"CHANNEL_PINS_UPDATE" => channel.pins_update,
"CALL_CREATE" => call.create,
"CALL_UPDATE" => call.update,
"CALL_DELETE" => call.delete,
- "THREAD_CREATE" => thread.create,
- "THREAD_UPDATE" => thread.update,
- "THREAD_DELETE" => thread.delete,
- "THREAD_LIST_SYNC" => thread.list_sync,
- "THREAD_MEMBER_UPDATE" => thread.member_update,
- "THREAD_MEMBERS_UPDATE" => thread.members_update,
- "GUILD_CREATE" => guild.create,
- "GUILD_UPDATE" => guild.update,
- "GUILD_DELETE" => guild.delete,
+ "THREAD_CREATE" => thread.create, // TODO
+ "THREAD_UPDATE" => thread.update ThreadUpdate: Channel,
+ "THREAD_DELETE" => thread.delete, // TODO
+ "THREAD_LIST_SYNC" => thread.list_sync, // TODO
+ "THREAD_MEMBER_UPDATE" => thread.member_update, // TODO
+ "THREAD_MEMBERS_UPDATE" => thread.members_update, // TODO
+ "GUILD_CREATE" => guild.create, // TODO
+ "GUILD_UPDATE" => guild.update, // TODO
+ "GUILD_DELETE" => guild.delete, // TODO
"GUILD_AUDIT_LOG_ENTRY_CREATE" => guild.audit_log_entry_create,
- "GUILD_BAN_ADD" => guild.ban_add,
- "GUILD_BAN_REMOVE" => guild.ban_remove,
- "GUILD_EMOJIS_UPDATE" => guild.emojis_update,
- "GUILD_STICKERS_UPDATE" => guild.stickers_update,
+ "GUILD_BAN_ADD" => guild.ban_add, // TODO
+ "GUILD_BAN_REMOVE" => guild.ban_remove, // TODO
+ "GUILD_EMOJIS_UPDATE" => guild.emojis_update, // TODO
+ "GUILD_STICKERS_UPDATE" => guild.stickers_update, // TODO
"GUILD_INTEGRATIONS_UPDATE" => guild.integrations_update,
"GUILD_MEMBER_ADD" => guild.member_add,
"GUILD_MEMBER_REMOVE" => guild.member_remove,
- "GUILD_MEMBER_UPDATE" => guild.member_update,
- "GUILD_MEMBERS_CHUNK" => guild.members_chunk,
- "GUILD_ROLE_CREATE" => guild.role_create,
- "GUILD_ROLE_UPDATE" => guild.role_update,
- "GUILD_ROLE_DELETE" => guild.role_delete,
- "GUILD_SCHEDULED_EVENT_CREATE" => guild.role_scheduled_event_create,
- "GUILD_SCHEDULED_EVENT_UPDATE" => guild.role_scheduled_event_update,
- "GUILD_SCHEDULED_EVENT_DELETE" => guild.role_scheduled_event_delete,
+ "GUILD_MEMBER_UPDATE" => guild.member_update, // TODO
+ "GUILD_MEMBERS_CHUNK" => guild.members_chunk, // TODO
+ "GUILD_ROLE_CREATE" => guild.role_create GuildRoleCreate: Guild,
+ "GUILD_ROLE_UPDATE" => guild.role_update GuildRoleUpdate: RoleObject,
+ "GUILD_ROLE_DELETE" => guild.role_delete, // TODO
+ "GUILD_SCHEDULED_EVENT_CREATE" => guild.role_scheduled_event_create, // TODO
+ "GUILD_SCHEDULED_EVENT_UPDATE" => guild.role_scheduled_event_update, // TODO
+ "GUILD_SCHEDULED_EVENT_DELETE" => guild.role_scheduled_event_delete, // TODO
"GUILD_SCHEDULED_EVENT_USER_ADD" => guild.role_scheduled_event_user_add,
"GUILD_SCHEDULED_EVENT_USER_REMOVE" => guild.role_scheduled_event_user_remove,
- "PASSIVE_UPDATE_V1" => guild.passive_update_v1,
- "INTEGRATION_CREATE" => integration.create,
- "INTEGRATION_UPDATE" => integration.update,
- "INTEGRATION_DELETE" => integration.delete,
- "INTERACTION_CREATE" => interaction.create,
- "INVITE_CREATE" => invite.create,
- "INVITE_DELETE" => invite.delete,
+ "PASSIVE_UPDATE_V1" => guild.passive_update_v1, // TODO
+ "INTEGRATION_CREATE" => integration.create, // TODO
+ "INTEGRATION_UPDATE" => integration.update, // TODO
+ "INTEGRATION_DELETE" => integration.delete, // TODO
+ "INTERACTION_CREATE" => interaction.create, // TODO
+ "INVITE_CREATE" => invite.create, // TODO
+ "INVITE_DELETE" => invite.delete, // TODO
"MESSAGE_CREATE" => message.create,
- "MESSAGE_UPDATE" => message.update,
+ "MESSAGE_UPDATE" => message.update, // TODO
"MESSAGE_DELETE" => message.delete,
"MESSAGE_DELETE_BULK" => message.delete_bulk,
- "MESSAGE_REACTION_ADD" => message.reaction_add,
- "MESSAGE_REACTION_REMOVE" => message.reaction_remove,
- "MESSAGE_REACTION_REMOVE_ALL" => message.reaction_remove_all,
- "MESSAGE_REACTION_REMOVE_EMOJI" => message.reaction_remove_emoji,
+ "MESSAGE_REACTION_ADD" => message.reaction_add, // TODO
+ "MESSAGE_REACTION_REMOVE" => message.reaction_remove, // TODO
+ "MESSAGE_REACTION_REMOVE_ALL" => message.reaction_remove_all, // TODO
+ "MESSAGE_REACTION_REMOVE_EMOJI" => message.reaction_remove_emoji, // TODO
"MESSAGE_ACK" => message.ack,
- "PRESENCE_UPDATE" => user.presence_update,
+ "PRESENCE_UPDATE" => user.presence_update, // TODO
"RELATIONSHIP_ADD" => relationship.add,
"RELATIONSHIP_REMOVE" => relationship.remove,
"STAGE_INSTANCE_CREATE" => stage_instance.create,
- "STAGE_INSTANCE_UPDATE" => stage_instance.update,
+ "STAGE_INSTANCE_UPDATE" => stage_instance.update, // TODO
"STAGE_INSTANCE_DELETE" => stage_instance.delete,
- "USER_UPDATE" => user.update,
+ "TYPING_START" => user.typing_start,
+ "USER_UPDATE" => user.update, // TODO
"USER_GUILD_SETTINGS_UPDATE" => user.guild_settings_update,
- "VOICE_STATE_UPDATE" => voice.state_update,
+ "VOICE_STATE_UPDATE" => voice.state_update, // TODO
"VOICE_SERVER_UPDATE" => voice.server_update,
"WEBHOOKS_UPDATE" => webhooks.update
);
@@ -671,6 +730,7 @@ impl Gateway {
/// Handles sending heartbeats to the gateway in another thread
#[allow(dead_code)] // FIXME: Remove this, once HeartbeatHandler is used
+#[derive(Debug)]
struct HeartbeatHandler {
/// How ofter heartbeats need to be sent at a minimum
pub heartbeat_interval: Duration,
@@ -857,7 +917,7 @@ impl GatewayEvent {
}
}
-mod events {
+pub mod events {
use super::*;
#[derive(Default, Debug)]
@@ -880,6 +940,7 @@ mod events {
pub webhooks: Webhooks,
pub gateway_identify_payload: GatewayEvent,
pub gateway_resume: GatewayEvent,
+ pub error: GatewayEvent,
}
#[derive(Default, Debug)]
@@ -927,7 +988,7 @@ mod events {
pub update: GatewayEvent,
pub guild_settings_update: GatewayEvent,
pub presence_update: GatewayEvent,
- pub typing_start_event: GatewayEvent,
+ pub typing_start: GatewayEvent,
}
#[derive(Default, Debug)]
diff --git a/src/instance.rs b/src/instance.rs
index 9795557..72bf350 100644
--- a/src/instance.rs
+++ b/src/instance.rs
@@ -1,24 +1,23 @@
-use std::cell::RefCell;
+//! Instance and ChorusUser objects.
+
use std::collections::HashMap;
use std::fmt;
-use std::rc::Rc;
+
+use std::sync::{Arc, RwLock};
use reqwest::Client;
use serde::{Deserialize, Serialize};
-use crate::api::{Limit, LimitType};
use crate::errors::ChorusResult;
use crate::gateway::{Gateway, GatewayHandle};
use crate::ratelimiter::ChorusRequest;
use crate::types::types::subconfigs::limits::rates::RateLimits;
-use crate::types::{GeneralConfiguration, User, UserSettings};
+use crate::types::{GeneralConfiguration, Limit, LimitType, User, UserSettings};
use crate::UrlBundle;
-#[derive(Debug, Clone)]
-/**
-The [`Instance`] what you will be using to perform all sorts of actions on the Spacebar server.
-If `limits_information` is `None`, then the instance will not be rate limited.
- */
+#[derive(Debug, Clone, Default)]
+/// The [`Instance`]; what you will be using to perform all sorts of actions on the Spacebar server.
+/// If `limits_information` is `None`, then the instance will not be rate limited.
pub struct Instance {
pub urls: UrlBundle,
pub instance_info: GeneralConfiguration,
@@ -26,19 +25,14 @@ pub struct Instance {
pub client: Client,
}
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct LimitsInformation {
pub ratelimits: HashMap,
pub configuration: RateLimits,
}
impl Instance {
- /// Creates a new [`Instance`].
- /// # Arguments
- /// * `urls` - The [`URLBundle`] that contains all the URLs that are needed to connect to the Spacebar server.
- /// * `requester` - The [`LimitedRequester`] that will be used to make requests to the Spacebar server.
- /// # Errors
- /// * [`InstanceError`] - If the instance cannot be created.
+ /// Creates a new [`Instance`] from the [relevant instance urls](UrlBundle), where `limited` is whether or not to automatically use rate limits.
pub async fn new(urls: UrlBundle, limited: bool) -> ChorusResult {
let limits_information;
if limited {
@@ -89,17 +83,20 @@ impl fmt::Display for Token {
}
}
-#[derive(Debug)]
-pub struct UserMeta {
- pub belongs_to: Rc>,
+#[derive(Debug, Clone)]
+/// A ChorusUser is a representation of an authenticated user on an [Instance].
+/// It is used for most authenticated actions on a Spacebar server.
+/// It also has its own [Gateway] connection.
+pub struct ChorusUser {
+ pub belongs_to: Arc>,
pub token: String,
pub limits: Option>,
- pub settings: UserSettings,
- pub object: User,
+ pub settings: Arc>,
+ pub object: Arc>,
pub gateway: GatewayHandle,
}
-impl UserMeta {
+impl ChorusUser {
pub fn token(&self) -> String {
self.token.clone()
}
@@ -108,15 +105,20 @@ impl UserMeta {
self.token = token;
}
+ /// Creates a new [ChorusUser] from existing data.
+ ///
+ /// # Notes
+ /// This isn't the prefered way to create a ChorusUser.
+ /// See [Instance::login_account] and [Instance::register_account] instead.
pub fn new(
- belongs_to: Rc>,
+ belongs_to: Arc>,
token: String,
limits: Option>,
- settings: UserSettings,
- object: User,
+ settings: Arc>,
+ object: Arc>,
gateway: GatewayHandle,
- ) -> UserMeta {
- UserMeta {
+ ) -> ChorusUser {
+ ChorusUser {
belongs_to,
token,
limits,
@@ -127,21 +129,22 @@ impl UserMeta {
}
/// Creates a new 'shell' of a user. The user does not exist as an object, and exists so that you have
- /// a UserMeta object to make Rate Limited requests with. This is useful in scenarios like
+ /// a ChorusUser object to make Rate Limited requests with. This is useful in scenarios like
/// registering or logging in to the Instance, where you do not yet have a User object, but still
/// need to make a RateLimited request. To use the [`GatewayHandle`], you will have to identify
/// first.
- pub(crate) async fn shell(instance: Rc>, token: String) -> UserMeta {
- let settings = UserSettings::default();
- let object = User::default();
- let wss_url = instance.borrow().urls.wss.clone();
+ pub(crate) async fn shell(instance: Arc>, token: String) -> ChorusUser {
+ let settings = Arc::new(RwLock::new(UserSettings::default()));
+ let object = Arc::new(RwLock::new(User::default()));
+ let wss_url = instance.read().unwrap().urls.wss.clone();
// Dummy gateway object
let gateway = Gateway::new(wss_url).await.unwrap();
- UserMeta {
+ ChorusUser {
token,
belongs_to: instance.clone(),
limits: instance
- .borrow()
+ .read()
+ .unwrap()
.limits_information
.as_ref()
.map(|info| info.ratelimits.clone()),
diff --git a/src/lib.rs b/src/lib.rs
index 77425b8..e63c41d 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,4 +1,19 @@
+//! A library for interacting with one or multiple Spacebar-compatible APIs and Gateways.
+//!
+//! # About
+//!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.
+#![doc(
+ html_logo_url = "https://raw.githubusercontent.com/polyphony-chat/design/main/branding/polyphony-chorus-round-8bit.png"
+)]
#![allow(clippy::module_inception)]
+#![deny(
+ missing_debug_implementations,
+ clippy::extra_unused_lifetimes,
+ clippy::from_over_into,
+ clippy::needless_borrow,
+ clippy::new_without_default,
+ clippy::useless_conversion
+)]
use url::{ParseError, Url};
@@ -15,16 +30,26 @@ pub mod types;
#[cfg(feature = "client")]
pub mod voice;
-#[derive(Clone, Default, Debug, PartialEq, Eq)]
-/// A URLBundle is a struct which bundles together the API-, Gateway- and CDN-URLs of a Spacebar
-/// instance.
+#[derive(Clone, Default, Debug, PartialEq, Eq, Hash)]
+/// A URLBundle bundles together the API-, Gateway- and CDN-URLs of a Spacebar instance.
+///
+/// # Notes
+/// All the urls can be found on the /api/policies/instance/domains endpoint of a spacebar server
pub struct UrlBundle {
+ /// The api's url.
+ /// Ex: `https://old.server.spacebar.chat/api`
pub api: String,
+ /// The gateway websocket url.
+ /// Note that because this is a websocket url, it will always start with `wss://` or `ws://`
+ /// Ex: `wss://gateway.old.server.spacebar.chat`
pub wss: String,
+ /// The CDN's url.
+ /// Ex: `https://cdn.old.server.spacebar.chat`
pub cdn: String,
}
impl UrlBundle {
+ /// Creates a new UrlBundle from the relevant urls.
pub fn new(api: String, wss: String, cdn: String) -> Self {
Self {
api: UrlBundle::parse_url(api),
@@ -33,9 +58,10 @@ impl UrlBundle {
}
}
- /// parse(url: String) parses a URL using the Url library and formats it in a standardized
- /// way. If no protocol is given, HTTP (not HTTPS) is assumed.
- /// # Example:
+ /// Parses a URL using the Url library and formats it in a standardized way.
+ /// If no protocol is given, HTTP (not HTTPS) is assumed.
+ ///
+ /// # Examples:
/// ```rs
/// let url = parse_url("localhost:3000");
/// ```
diff --git a/src/ratelimiter.rs b/src/ratelimiter.rs
index 9227737..88d4a02 100644
--- a/src/ratelimiter.rs
+++ b/src/ratelimiter.rs
@@ -1,3 +1,5 @@
+//! Ratelimiter and request handling functionality.
+
use std::collections::HashMap;
use log::{self, debug};
@@ -6,37 +8,81 @@ use serde::Deserialize;
use serde_json::from_str;
use crate::{
- api::{Limit, LimitType},
errors::{ChorusError, ChorusResult},
- instance::UserMeta,
- types::{types::subconfigs::limits::rates::RateLimits, LimitsConfiguration},
+ instance::ChorusUser,
+ types::{types::subconfigs::limits::rates::RateLimits, Limit, LimitType, LimitsConfiguration},
};
/// Chorus' request struct. This struct is used to send rate-limited requests to the Spacebar server.
/// See for more information.
+#[derive(Debug)]
pub struct ChorusRequest {
pub request: RequestBuilder,
pub limit_type: LimitType,
}
impl ChorusRequest {
+ /// Makes a new [`ChorusRequest`].
+ /// # Arguments
+ /// * `method` - The HTTP method to use. Must be one of the following:
+ /// * [`http::Method::GET`]
+ /// * [`http::Method::POST`]
+ /// * [`http::Method::PUT`]
+ /// * [`http::Method::DELETE`]
+ /// * [`http::Method::PATCH`]
+ /// * [`http::Method::HEAD`]
+ #[allow(unused_variables)] // TODO: Add mfa_token to request, once we figure out *how* to do so correctly
+ pub fn new(
+ method: http::Method,
+ url: &str,
+ body: Option
+