twilight_http/request/application/interaction/
update_response.rs

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

twilight_http/request/application/interaction/
update_response.rs
