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