feat(cache,http,model): guild timeouts

cache/in-memory/src/event/interaction.rs

@@ -104,6 +104,7 @@ mod tests {
                             UserId::new(7).expect("non zero"),
                             InteractionMember {
                                 avatar: None,
+                                communication_disabled_until: None,
                                 joined_at: timestamp,
                                 nick: None,
                                 pending: false,
@@ -149,6 +150,7 @@ mod tests {
                                 kind: MessageType::Regular,
                                 member: Some(PartialMember {
                                     avatar: None,
+                                    communication_disabled_until: None,
                                     deaf: false,
                                     joined_at: timestamp,
                                     mute: false,
@@ -223,6 +225,7 @@ mod tests {
                 kind: InteractionType::ApplicationCommand,
                 member: Some(PartialMember {
                     avatar: None,
+                    communication_disabled_until: None,
                     deaf: false,
                     joined_at: timestamp,
                     mute: false,

cache/in-memory/src/event/member.rs

@@ -33,6 +33,7 @@ impl InMemoryCache {
         self.cache_user(Cow::Owned(member.user), Some(guild_id));
         let cached = CachedMember {
             avatar: member.avatar,
+            communication_disabled_until: member.communication_disabled_until,
             deaf: Some(member.deaf),
             guild_id,
             joined_at: member.joined_at,
@@ -71,6 +72,7 @@ impl InMemoryCache {
 
         let cached = CachedMember {
             avatar: member.avatar.to_owned(),
+            communication_disabled_until: member.communication_disabled_until.to_owned(),
             deaf: Some(member.deaf),
             guild_id,
             joined_at: member.joined_at,
@@ -105,6 +107,7 @@ impl InMemoryCache {
 
         let cached = CachedMember {
             avatar,
+            communication_disabled_until: member.communication_disabled_until.to_owned(),
             deaf,
             guild_id,
             joined_at: member.joined_at,

cache/in-memory/src/event/message.rs

@@ -180,6 +180,7 @@ mod tests {
             kind: MessageType::Regular,
             member: Some(PartialMember {
                 avatar: None,
+                communication_disabled_until: None,
                 deaf: false,
                 joined_at,
                 mute: false,

cache/in-memory/src/event/voice_state.rs

@@ -332,6 +332,7 @@ mod tests {
             guild_id: Some(GuildId::new(2).expect("non zero")),
             member: Some(Member {
                 avatar: None,
+                communication_disabled_until: None,
                 deaf: false,
                 guild_id: GuildId::new(2).expect("non zero"),
                 joined_at,

cache/in-memory/src/lib.rs

@@ -920,6 +920,7 @@ mod tests {
             guild_id,
             Member {
                 avatar: None,
+                communication_disabled_until: None,
                 deaf: false,
                 guild_id,
                 joined_at,

cache/in-memory/src/model/member.rs

@@ -12,6 +12,7 @@ use twilight_model::{
 #[derive(Clone, Debug, Eq, PartialEq, Serialize)]
 pub struct CachedMember {
     pub(crate) avatar: Option<String>,
+    pub(crate) communication_disabled_until: Option<Timestamp>,
     pub(crate) deaf: Option<bool>,
     pub(crate) guild_id: GuildId,
     pub(crate) joined_at: Timestamp,
@@ -29,6 +30,19 @@ impl CachedMember {
         self.avatar.as_deref()
     }
 
+    /// When the user can resume communication in a guild again.
+    ///
+    /// Checking if this value is [`Some`] is not enough to know if a used is currently
+    /// timed out as Discord doesn't send any events when the timeout expires, and
+    /// therefore the cache is not updated accordingly. You should ensure that the
+    /// provided [`Timestamp`] is not in the past. See [discord-api-docs#4269] for
+    /// more information.
+    ///
+    /// [discord-api-docs#4269]: https://github.com/discord/discord-api-docs/issues/4269
+    pub const fn communication_disabled_until(&self) -> Option<Timestamp> {
+        self.communication_disabled_until
+    }
+
     /// Whether the member is deafened in a voice channel.
     pub const fn deaf(&self) -> Option<bool> {
         self.deaf
@@ -80,6 +94,7 @@ impl PartialEq<Member> for CachedMember {
     fn eq(&self, other: &Member) -> bool {
         (
             &self.avatar,
+            &self.communication_disabled_until,
             self.deaf,
             self.joined_at,
             self.mute,
@@ -90,6 +105,7 @@ impl PartialEq<Member> for CachedMember {
             self.user_id,
         ) == (
             &other.avatar,
+            &other.communication_disabled_until,
             Some(other.deaf),
             other.joined_at,
             Some(other.mute),
@@ -105,13 +121,15 @@ impl PartialEq<Member> for CachedMember {
 impl PartialEq<PartialMember> for CachedMember {
     fn eq(&self, other: &PartialMember) -> bool {
         (
+            &self.communication_disabled_until,
             self.deaf,
             self.joined_at,
             self.mute,
             &self.nick,
             self.premium_since,
             &self.roles,
         ) == (
+            &other.communication_disabled_until,
             Some(other.deaf),
             other.joined_at,
             Some(other.mute),
@@ -162,6 +180,7 @@ mod tests {
 
         CachedMember {
             avatar: None,
+            communication_disabled_until: None,
             deaf: Some(false),
             guild_id: GuildId::new(3).expect("non zero"),
             joined_at,
@@ -200,6 +219,7 @@ mod tests {
 
         let member = Member {
             avatar: None,
+            communication_disabled_until: None,
             deaf: false,
             guild_id: GuildId::new(3).expect("non zero"),
             joined_at,
@@ -220,6 +240,7 @@ mod tests {
 
         let member = PartialMember {
             avatar: None,
+            communication_disabled_until: None,
             deaf: false,
             joined_at,
             mute: true,

cache/in-memory/src/test.rs

@@ -50,6 +50,7 @@ pub fn cache_with_message_and_reactions() -> InMemoryCache {
         kind: MessageType::Regular,
         member: Some(PartialMember {
             avatar: None,
+            communication_disabled_until: None,
             deaf: false,
             joined_at,
             mute: false,
@@ -84,6 +85,7 @@ pub fn cache_with_message_and_reactions() -> InMemoryCache {
         guild_id: Some(GuildId::new(1).expect("non zero")),
         member: Some(Member {
             avatar: None,
+            communication_disabled_until: None,
             deaf: false,
             guild_id: GuildId::new(1).expect("non zero"),
             joined_at,
@@ -118,6 +120,7 @@ pub fn cache_with_message_and_reactions() -> InMemoryCache {
 
     reaction.member.replace(Member {
         avatar: None,
+        communication_disabled_until: None,
         deaf: false,
         guild_id: GuildId::new(1).expect("non zero"),
         joined_at,
@@ -215,6 +218,7 @@ pub fn member(id: UserId, guild_id: GuildId) -> Member {
 
     Member {
         avatar: None,
+        communication_disabled_until: None,
         deaf: false,
         guild_id,
         joined_at,

http/src/request/guild/member/update_guild_member.rs

@@ -10,7 +10,10 @@ use std::{
     error::Error,
     fmt::{Display, Formatter, Result as FmtResult},
 };
-use twilight_model::id::{ChannelId, GuildId, RoleId, UserId};
+use twilight_model::{
+    datetime::Timestamp,
+    id::{ChannelId, GuildId, RoleId, UserId},
+};
 
 /// The error created when the member can not be updated as configured.
 #[derive(Debug)]
@@ -50,6 +53,9 @@ impl Display for UpdateGuildMemberError {
             UpdateGuildMemberErrorType::NicknameInvalid => {
                 f.write_str("the nickname length is invalid")
             }
+            UpdateGuildMemberErrorType::TimeoutExpiryTimestampInvalid => {
+                f.write_str("the timeout expiry is more than 28 days from the current time")
+            }
         }
     }
 }
@@ -62,6 +68,8 @@ impl Error for UpdateGuildMemberError {}
 pub enum UpdateGuildMemberErrorType {
     /// The nickname is either empty or the length is more than 32 UTF-16 characters.
     NicknameInvalid,
+    /// The timeout expiry timestamp is more than 28 days from the current timestamp
+    TimeoutExpiryTimestampInvalid,
 }
 
 #[derive(Serialize)]
@@ -70,6 +78,8 @@ struct UpdateGuildMemberFields<'a> {
     #[serde(skip_serializing_if = "Option::is_none")]
     channel_id: Option<NullableField<ChannelId>>,
     #[serde(skip_serializing_if = "Option::is_none")]
+    communication_disabled_util: Option<NullableField<Timestamp>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     deaf: Option<bool>,
     #[serde(skip_serializing_if = "Option::is_none")]
     mute: Option<bool>,
@@ -98,6 +108,7 @@ impl<'a> UpdateGuildMember<'a> {
         Self {
             fields: UpdateGuildMemberFields {
                 channel_id: None,
+                communication_disabled_util: None,
                 deaf: None,
                 mute: None,
                 nick: None,
@@ -117,6 +128,36 @@ impl<'a> UpdateGuildMember<'a> {
         self
     }
 
+    /// Set the member's [Guild Timeout].
+    ///
+    /// The timestamp indicates when the user will be able to communicate again.
+    /// It can be up to 28 days in the future. Set to [`None`] to remove the
+    /// timeout. Requires the [`MODERATE_MEMBERS`] permission.
+    ///
+    /// [Guild Timeout]: https://support.discord.com/hc/en-us/articles/4413305239191-Time-Out-FAQ
+    /// [`MODERATE_MEMBERS`]: twilight_model::guild::Permissions::MODERATE_MEMBERS
+    ///
+    /// # Errors
+    /// Returns an [`UpdateGuildMemberErrorType::TimeoutExpiryTimestampInvalid`]
+    /// error type if the expiry timestamp is more than 28 days from the current time.
+    ///
+    pub fn communication_disabled_until(
+        mut self,
+        timestamp: Option<Timestamp>,
+    ) -> Result<Self, UpdateGuildMemberError> {
+        if let Some(timestamp) = timestamp {
+            if !validate_inner::communication_disabled_until(timestamp) {
+                return Err(UpdateGuildMemberError {
+                    kind: UpdateGuildMemberErrorType::TimeoutExpiryTimestampInvalid,
+                });
+            }
+        }
+
+        self.fields.communication_disabled_util = Some(NullableField(timestamp));
+
+        Ok(self)
+    }
+
     /// If true, restrict the member's ability to hear sound from a voice channel.
     pub const fn deaf(mut self, deaf: bool) -> Self {
         self.fields.deaf = Some(deaf);
@@ -227,6 +268,7 @@ mod tests {
 
         let body = UpdateGuildMemberFields {
             channel_id: None,
+            communication_disabled_util: None,
             deaf: Some(true),
             mute: Some(true),
             nick: None,
@@ -252,6 +294,7 @@ mod tests {
 
         let body = UpdateGuildMemberFields {
             channel_id: None,
+            communication_disabled_util: None,
             deaf: None,
             mute: None,
             nick: Some(NullableField(None)),
@@ -276,6 +319,7 @@ mod tests {
 
         let body = UpdateGuildMemberFields {
             channel_id: None,
+            communication_disabled_util: None,
             deaf: None,
             mute: None,
             nick: Some(NullableField(Some("foo"))),

http/src/request/validate.rs

@@ -7,10 +7,12 @@ use super::{application::InteractionError, guild::sticker::StickerValidationErro
 use std::{
     error::Error,
     fmt::{Display, Formatter, Result as FmtResult},
+    time::{SystemTime, UNIX_EPOCH},
 };
 use twilight_model::{
     application::component::{select_menu::SelectMenuOption, Component, ComponentType},
     channel::{embed::Embed, ChannelType},
+    datetime::Timestamp,
 };
 
 /// A provided [`Component`] is invalid.
@@ -1175,6 +1177,26 @@ fn _sticker_tags(value: &str) -> bool {
         .contains(&len)
 }
 
+pub fn communication_disabled_until(timestamp: Timestamp) -> bool {
+    _communication_disabled_until(timestamp)
+}
+
+const COMMUNICATION_DISABLED_MAX_DURATION: i64 = 28 * 24 * 60 * 60;
+
+#[allow(clippy::cast_possible_wrap)] // casting of unix timestamp should never wrap
+fn _communication_disabled_until(timestamp: Timestamp) -> bool {
+    let now = SystemTime::now().duration_since(UNIX_EPOCH);
+
+    match now {
+        Ok(now) => {
+            let end = timestamp.as_secs();
+
+            end - now.as_secs() as i64 <= COMMUNICATION_DISABLED_MAX_DURATION
+        }
+        Err(_) => false,
+    }
+}
+
 /// Validate the number of guild command permission overwrites.
 ///
 /// The maximum number of commands allowed in a guild is defined by

model/src/application/interaction/application_command/data/resolved.rs

@@ -40,6 +40,7 @@ pub struct InteractionMember {
     /// Member's guild avatar.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub avatar: Option<String>,
+    pub communication_disabled_until: Option<Timestamp>,
     pub joined_at: Timestamp,
     pub nick: Option<String>,
     /// Whether the user has yet to pass the guild's Membership Screening
@@ -95,6 +96,7 @@ mod tests {
                 UserId::new(300).expect("non zero"),
                 InteractionMember {
                     avatar: None,
+                    communication_disabled_until: None,
                     joined_at,
                     nick: None,
                     pending: false,
@@ -140,6 +142,7 @@ mod tests {
                     kind: MessageType::Regular,
                     member: Some(PartialMember {
                         avatar: None,
+                        communication_disabled_until: None,
                         deaf: false,
                         joined_at,
                         mute: false,
@@ -243,8 +246,10 @@ mod tests {
                 Token::Str("300"),
                 Token::Struct {
                     name: "InteractionMember",
-                    len: 5,
+                    len: 6,
                 },
+                Token::Str("communication_disabled_until"),
+                Token::None,
                 Token::Str("joined_at"),
                 Token::Str("2021-08-10T12:18:37.000000+00:00"),
                 Token::Str("nick"),
@@ -317,8 +322,10 @@ mod tests {
                 Token::Some,
                 Token::Struct {
                     name: "PartialMember",
-                    len: 7,
+                    len: 8,
                 },
+                Token::Str("communication_disabled_until"),
+                Token::None,
                 Token::Str("deaf"),
                 Token::Bool(false),
                 Token::Str("joined_at"),

model/src/application/interaction/message_component/mod.rs

@@ -152,6 +152,7 @@ mod tests {
             kind: InteractionType::MessageComponent,
             member: Some(PartialMember {
                 avatar: None,
+                communication_disabled_until: None,
                 deaf: false,
                 joined_at: timestamp,
                 mute: false,