twilight_http/request/application/interaction/
update_followup.rs

1//! Update a followup message created from a interaction.
2
3use crate::{
4    client::Client,
5    error::Error,
6    request::{
7        attachment::{AttachmentManager, PartialAttachment},
8        Nullable, Request, TryIntoRequest,
9    },
10    response::{Response, ResponseFuture},
11    routing::Route,
12};
13use serde::Serialize;
14use std::future::IntoFuture;
15use twilight_model::{
16    channel::message::{AllowedMentions, Component, Embed, Message},
17    http::attachment::Attachment,
18    id::{
19        marker::{ApplicationMarker, AttachmentMarker, MessageMarker},
20        Id,
21    },
22};
23use twilight_validate::message::{
24    attachment as validate_attachment, components as validate_components,
25    content as validate_content, embeds as validate_embeds, MessageValidationError,
26};
27
28#[derive(Serialize)]
29struct UpdateFollowupFields<'a> {
30    #[serde(skip_serializing_if = "Option::is_none")]
31    allowed_mentions: Option<Nullable<&'a AllowedMentions>>,
32    /// List of attachments to keep, and new attachments to add.
33    #[serde(skip_serializing_if = "Option::is_none")]
34    attachments: Option<Nullable<Vec<PartialAttachment<'a>>>>,
35    #[serde(skip_serializing_if = "Option::is_none")]
36    components: Option<Nullable<&'a [Component]>>,
37    #[serde(skip_serializing_if = "Option::is_none")]
38    content: Option<Nullable<&'a str>>,
39    #[serde(skip_serializing_if = "Option::is_none")]
40    embeds: Option<Nullable<&'a [Embed]>>,
41    #[serde(skip_serializing_if = "Option::is_none")]
42    payload_json: Option<&'a [u8]>,
43}
44
45/// Edit a followup message of an interaction, by its token and the message ID.
46///
47/// You can pass [`None`] to any of the methods to remove the associated field.
48/// Pass [`None`] to [`content`] to remove the content. You must ensure that the
49/// message still contains at least one of [`attachments`], [`components`],
50/// [`content`], or [`embeds`].
51///
52/// This endpoint is not bound to the application's global rate limit.
53///
54/// # Examples
55///
56/// Update a followup message by setting the content to `test <@3>` -
57/// attempting to mention user ID 3 - while specifying that no entities can be
58/// mentioned.
59///
60/// ```no_run
61/// # #[tokio::main] async fn main() -> Result<(), Box<dyn std::error::Error>> {
62/// use std::env;
63/// use twilight_http::Client;
64/// use twilight_model::{channel::message::AllowedMentions, id::Id};
65///
66/// let client = Client::new(env::var("DISCORD_TOKEN")?);
67/// let application_id = Id::new(1);
68///
69/// client
70///     .interaction(application_id)
71///     .update_followup("token here", Id::new(2))
72///     // By creating a default set of allowed mentions, no entity can be
73///     // mentioned.
74///     .allowed_mentions(Some(&AllowedMentions::default()))
75///     .content(Some("test <@3>"))
76///     .await?;
77/// # Ok(()) }
78/// ```
79///
80/// [`attachments`]: Self::attachments
81/// [`components`]: Self::components
82/// [`content`]: Self::content
83/// [`embeds`]: Self::embeds
84#[must_use = "requests must be configured and executed"]
85pub struct UpdateFollowup<'a> {
86    application_id: Id<ApplicationMarker>,
87    attachment_manager: AttachmentManager<'a>,
88    fields: Result<UpdateFollowupFields<'a>, MessageValidationError>,
89    http: &'a Client,
90    message_id: Id<MessageMarker>,
91    token: &'a str,
92}
93
94impl<'a> UpdateFollowup<'a> {
95    pub(crate) const fn new(
96        http: &'a Client,
97        application_id: Id<ApplicationMarker>,
98        token: &'a str,
99        message_id: Id<MessageMarker>,
100    ) -> Self {
101        Self {
102            application_id,
103            attachment_manager: AttachmentManager::new(),
104            fields: Ok(UpdateFollowupFields {
105                allowed_mentions: None,
106                attachments: None,
107                components: None,
108                content: None,
109                embeds: None,
110                payload_json: None,
111            }),
112            http,
113            message_id,
114            token,
115        }
116    }
117
118    /// Specify the [`AllowedMentions`] for the message.
119    ///
120    /// Unless otherwise called, the request will use the client's default
121    /// allowed mentions. Set to `None` to ignore this default.
122    pub fn allowed_mentions(mut self, allowed_mentions: Option<&'a AllowedMentions>) -> Self {
123        if let Ok(fields) = self.fields.as_mut() {
124            fields.allowed_mentions = Some(Nullable(allowed_mentions));
125        }
126
127        self
128    }
129
130    /// Attach multiple new files to the message.
131    ///
132    /// This method clears previous calls.
133    ///
134    /// # Errors
135    ///
136    /// Returns an error of type [`AttachmentDescriptionTooLarge`] if
137    /// the attachments' description is too large.
138    ///
139    /// Returns an error of type [`AttachmentFilename`] if any filename is
140    /// invalid.
141    ///
142    /// [`AttachmentDescriptionTooLarge`]: twilight_validate::message::MessageValidationErrorType::AttachmentDescriptionTooLarge
143    /// [`AttachmentFilename`]: twilight_validate::message::MessageValidationErrorType::AttachmentFilename
144    pub fn attachments(mut self, attachments: &'a [Attachment]) -> Self {
145        if self.fields.is_ok() {
146            if let Err(source) = attachments.iter().try_for_each(validate_attachment) {
147                self.fields = Err(source);
148            } else {
149                self.attachment_manager = self
150                    .attachment_manager
151                    .set_files(attachments.iter().collect());
152            }
153        }
154
155        self
156    }
157
158    /// Set the message's list of [`Component`]s.
159    ///
160    /// Calling this method will clear previous calls.
161    ///
162    /// # Editing
163    ///
164    /// Pass [`None`] to clear existing components.
165    ///
166    /// # Errors
167    ///
168    /// Refer to the errors section of
169    /// [`twilight_validate::component::component`] for a list of errors that
170    /// may be returned as a result of validating each provided component.
171    pub fn components(mut self, components: Option<&'a [Component]>) -> Self {
172        self.fields = self.fields.and_then(|mut fields| {
173            if let Some(components) = components {
174                validate_components(components)?;
175            }
176
177            fields.components = Some(Nullable(components));
178
179            Ok(fields)
180        });
181
182        self
183    }
184
185    /// Set the message's content.
186    ///
187    /// The maximum length is 2000 UTF-16 characters.
188    ///
189    /// # Editing
190    ///
191    /// Pass [`None`] to remove the message content. This is impossible if it
192    /// would leave the message empty of `attachments`, `content`, or `embeds`.
193    ///
194    /// # Errors
195    ///
196    /// Returns an error of type [`ContentInvalid`] if the content length is too
197    /// long.
198    ///
199    /// [`ContentInvalid`]: twilight_validate::message::MessageValidationErrorType::ContentInvalid
200    pub fn content(mut self, content: Option<&'a str>) -> Self {
201        self.fields = self.fields.and_then(|mut fields| {
202            if let Some(content_ref) = content.as_ref() {
203                validate_content(content_ref)?;
204            }
205
206            fields.content = Some(Nullable(content));
207
208            Ok(fields)
209        });
210
211        self
212    }
213
214    /// Set the message's list of embeds.
215    ///
216    /// Calling this method will clear previous calls.
217    ///
218    /// The amount of embeds must not exceed [`EMBED_COUNT_LIMIT`]. The total
219    /// character length of each embed must not exceed [`EMBED_TOTAL_LENGTH`]
220    /// characters. Additionally, the internal fields also have character
221    /// limits. See [Discord Docs/Embed Limits].
222    ///
223    /// # Editing
224    ///
225    /// To keep all embeds, do not call this method. To modify one or more
226    /// embeds in the message, acquire them from the previous message, mutate
227    /// them in place, then pass that list to this method. To remove all embeds,
228    /// pass [`None`]. This is impossible if it would leave the message empty of
229    /// `attachments`, `content`, or `embeds`.
230    ///
231    /// # Examples
232    ///
233    /// Create an embed and update the message with the new embed. The content
234    /// of the original message is unaffected and only the embed(s) are
235    /// modified.
236    ///
237    /// ```no_run
238    /// # #[tokio::main] async fn main() -> Result<(), Box<dyn std::error::Error>> {
239    /// use twilight_http::Client;
240    /// use twilight_model::id::Id;
241    /// use twilight_util::builder::embed::EmbedBuilder;
242    ///
243    /// let client = Client::new("token".to_owned());
244    /// let application_id = Id::new(1);
245    /// let message_id = Id::new(2);
246    ///
247    /// let embed = EmbedBuilder::new()
248    ///     .description(
249    ///         "Powerful, flexible, and scalable ecosystem of Rust \
250    ///     libraries for the Discord API.",
251    ///     )
252    ///     .title("Twilight")
253    ///     .url("https://twilight.rs")
254    ///     .validate()?
255    ///     .build();
256    ///
257    /// client
258    ///     .interaction(application_id)
259    ///     .update_followup("token", message_id)
260    ///     .embeds(Some(&[embed]))
261    ///     .await?;
262    /// # Ok(()) }
263    /// ```
264    ///
265    /// # Errors
266    ///
267    /// Returns an error of type [`TooManyEmbeds`] if there are too many embeds.
268    ///
269    /// Otherwise, refer to the errors section of
270    /// [`twilight_validate::embed::embed`] for a list of errors that may occur.
271    ///
272    /// [`EMBED_COUNT_LIMIT`]: twilight_validate::message::EMBED_COUNT_LIMIT
273    /// [`EMBED_TOTAL_LENGTH`]: twilight_validate::embed::EMBED_TOTAL_LENGTH
274    /// [`TooManyEmbeds`]: twilight_validate::message::MessageValidationErrorType::TooManyEmbeds
275    /// [Discord Docs/Embed Limits]: https://discord.com/developers/docs/resources/channel#embed-limits
276    pub fn embeds(mut self, embeds: Option<&'a [Embed]>) -> Self {
277        self.fields = self.fields.and_then(|mut fields| {
278            if let Some(embeds) = embeds {
279                validate_embeds(embeds)?;
280            }
281
282            fields.embeds = Some(Nullable(embeds));
283
284            Ok(fields)
285        });
286
287        self
288    }
289
290    /// Specify multiple [`Id<AttachmentMarker>`]s already present in the target
291    /// message to keep.
292    ///
293    /// If called, all unspecified attachments (except ones added with
294    /// [`attachments`]) will be removed from the message. This is impossible if
295    /// it would leave the message empty of `attachments`, `content`, or
296    /// `embeds`. If not called, all attachments will be kept.
297    ///
298    /// [`attachments`]: Self::attachments
299    pub fn keep_attachment_ids(mut self, attachment_ids: &'a [Id<AttachmentMarker>]) -> Self {
300        if let Ok(fields) = self.fields.as_mut() {
301            self.attachment_manager = self.attachment_manager.set_ids(attachment_ids.to_vec());
302
303            // Set an empty list. This will be overwritten in `TryIntoRequest` if
304            // the actual list is not empty.
305            fields.attachments = Some(Nullable(Some(Vec::new())));
306        }
307
308        self
309    }
310
311    /// JSON encoded body of any additional request fields.
312    ///
313    /// If this method is called, all other fields are ignored, except for
314    /// [`attachments`]. See [Discord Docs/Uploading Files].
315    ///
316    /// # Examples
317    ///
318    /// See [`ExecuteWebhook::payload_json`] for examples.
319    ///
320    /// [`attachments`]: Self::attachments
321    /// [`ExecuteWebhook::payload_json`]: crate::request::channel::webhook::ExecuteWebhook::payload_json
322    /// [Discord Docs/Uploading Files]: https://discord.com/developers/docs/reference#uploading-files
323    pub fn payload_json(mut self, payload_json: &'a [u8]) -> Self {
324        if let Ok(fields) = self.fields.as_mut() {
325            fields.payload_json = Some(payload_json);
326        }
327
328        self
329    }
330}
331
332impl IntoFuture for UpdateFollowup<'_> {
333    type Output = Result<Response<Message>, Error>;
334
335    type IntoFuture = ResponseFuture<Message>;
336
337    fn into_future(self) -> Self::IntoFuture {
338        let http = self.http;
339
340        match self.try_into_request() {
341            Ok(request) => http.request(request),
342            Err(source) => ResponseFuture::error(source),
343        }
344    }
345}
346
347impl TryIntoRequest for UpdateFollowup<'_> {
348    fn try_into_request(self) -> Result<Request, Error> {
349        let mut fields = self.fields.map_err(Error::validation)?;
350        let mut request = Request::builder(&Route::UpdateWebhookMessage {
351            message_id: self.message_id.get(),
352            thread_id: None,
353            token: self.token,
354            webhook_id: self.application_id.get(),
355        });
356
357        // Interaction executions don't need the authorization token, only the
358        // interaction token.
359        request = request.use_authorization_token(false);
360
361        // Set the default allowed mentions if required.
362        if fields.allowed_mentions.is_none() {
363            if let Some(allowed_mentions) = self.http.default_allowed_mentions() {
364                fields.allowed_mentions = Some(Nullable(Some(allowed_mentions)));
365            }
366        }
367
368        // Determine whether we need to use a multipart/form-data body or a JSON
369        // body.
370        if !self.attachment_manager.is_empty() {
371            let form = if let Some(payload_json) = fields.payload_json {
372                self.attachment_manager.build_form(payload_json)
373            } else {
374                fields.attachments = Some(Nullable(Some(
375                    self.attachment_manager.get_partial_attachments(),
376                )));
377
378                let fields = crate::json::to_vec(&fields).map_err(Error::json)?;
379
380                self.attachment_manager.build_form(fields.as_ref())
381            };
382
383            request = request.form(form);
384        } else if let Some(payload_json) = fields.payload_json {
385            request = request.body(payload_json.to_vec());
386        } else {
387            request = request.json(&fields);
388        }
389
390        request.build()
391    }
392}
393
394#[cfg(test)]
395mod tests {
396    use crate::{client::Client, request::TryIntoRequest};
397    use std::error::Error;
398    use twilight_http_ratelimiting::Path;
399    use twilight_model::id::Id;
400
401    #[test]
402    fn update_followup_message() -> Result<(), Box<dyn Error>> {
403        let application_id = Id::new(1);
404        let message_id = Id::new(2);
405        let token = "foo".to_owned();
406
407        let client = Client::new(String::new());
408        let req = client
409            .interaction(application_id)
410            .update_followup(&token, message_id)
411            .content(Some("test"))
412            .try_into_request()?;
413
414        assert!(!req.use_authorization_token());
415        assert_eq!(
416            &Path::WebhooksIdTokenMessagesId(application_id.get(), token),
417            req.ratelimit_path()
418        );
419
420        Ok(())
421    }
422}
twilight_http/request/application/interaction/update_followup.rs

twilight_http/request/application/interaction/
update_followup.rs
