twilight_http/request/channel/webhook/
update_webhook_message.rs

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

twilight_http/request/channel/webhook/
update_webhook_message.rs
