twilight_util/link/
webhook.rs

1//! Utilities for parsing webhook URLs.
2//!
3//! The URL is typically provided by the desktop client GUI when configuring a
4//! webhook integration.
5
6use std::{
7    error::Error,
8    fmt::{Display, Formatter, Result as FmtResult},
9    num::NonZeroU64,
10};
11use twilight_model::id::{marker::WebhookMarker, Id};
12
13/// Error when [parsing] a webhook URL.
14///
15/// [parsing]: parse
16#[derive(Debug)]
17pub struct WebhookParseError {
18    kind: WebhookParseErrorType,
19    source: Option<Box<dyn Error + Send + Sync>>,
20}
21
22impl WebhookParseError {
23    /// Immutable reference to the type of error that occurred.
24    #[must_use = "retrieving the type has no effect if left unused"]
25    pub const fn kind(&self) -> &WebhookParseErrorType {
26        &self.kind
27    }
28
29    /// Consume the error, returning the source error if there is any.
30    #[must_use = "consuming the error and retrieving the source has no effect if left unused"]
31    pub fn into_source(self) -> Option<Box<dyn Error + Send + Sync>> {
32        self.source
33    }
34
35    /// Consume the error, returning the owned error type and the source error.
36    #[must_use = "consuming the error into its parts has no effect if left unused"]
37    pub fn into_parts(self) -> (WebhookParseErrorType, Option<Box<dyn Error + Send + Sync>>) {
38        (self.kind, self.source)
39    }
40}
41
42impl Display for WebhookParseError {
43    fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult {
44        match self.kind {
45            WebhookParseErrorType::IdInvalid { .. } => {
46                f.write_str("url path segment isn't a valid ID")
47            }
48            WebhookParseErrorType::SegmentMissing => {
49                f.write_str("url is missing a required path segment")
50            }
51        }
52    }
53}
54
55impl Error for WebhookParseError {
56    fn source(&self) -> Option<&(dyn Error + 'static)> {
57        self.source
58            .as_ref()
59            .map(|source| &**source as &(dyn Error + 'static))
60    }
61}
62
63/// Type of [`WebhookParseError`] that occurred.
64#[derive(Debug)]
65#[non_exhaustive]
66pub enum WebhookParseErrorType {
67    /// ID segment in the URL path is not an integer.
68    IdInvalid,
69    /// Required segment of the URL path is missing.
70    SegmentMissing,
71}
72
73/// Parse the webhook ID and token from a webhook URL, if it exists in the
74/// string.
75///
76/// # Examples
77///
78/// Parse a webhook URL with a token:
79///
80/// ```
81/// use twilight_model::id::Id;
82/// use twilight_util::link::webhook;
83///
84/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
85/// let url = "https://canary.discord.com/api/webhooks/794590023369752587/tjxHaPHLKp9aEdSwJuLeHhHHGEqIxt1aay4I67FOP9uzsYEWmj0eJmDn-2ZvCYLyOb_K";
86///
87/// let (id, token) = webhook::parse(url)?;
88/// assert_eq!(Id::new(794590023369752587), id);
89/// assert_eq!(
90///     Some("tjxHaPHLKp9aEdSwJuLeHhHHGEqIxt1aay4I67FOP9uzsYEWmj0eJmDn-2ZvCYLyOb_K"),
91///     token,
92/// );
93/// # Ok(()) }
94/// ```
95///
96/// Parse a webhook URL without a token:
97///
98/// ```
99/// use twilight_model::id::Id;
100/// use twilight_util::link::webhook;
101///
102/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
103/// let url = "https://canary.discord.com/api/webhooks/794590023369752587";
104///
105/// let (id, token) = webhook::parse(url)?;
106/// assert_eq!(Id::new(794590023369752587), id);
107/// assert!(token.is_none());
108/// # Ok(()) }
109/// ```
110///
111/// # Errors
112///
113/// Returns [`WebhookParseErrorType::IdInvalid`] error type if the ID segment of
114/// the URL is not a valid integer.
115///
116/// Returns [`WebhookParseErrorType::SegmentMissing`] error type if one of the
117/// required segments is missing. This can be the "api" or "webhooks" standard
118/// segment of the URL or the segment containing the webhook ID.
119pub fn parse(url: &str) -> Result<(Id<WebhookMarker>, Option<&str>), WebhookParseError> {
120    let mut segments = {
121        let mut start = url.split("discord.com/api/webhooks/");
122        let path = start.nth(1).ok_or(WebhookParseError {
123            kind: WebhookParseErrorType::SegmentMissing,
124            source: None,
125        })?;
126
127        path.split('/')
128    };
129
130    let id_segment = segments.next().ok_or(WebhookParseError {
131        kind: WebhookParseErrorType::SegmentMissing,
132        source: None,
133    })?;
134
135    // If we don't have this check it'll return `IdInvalid`, which isn't right.
136    if id_segment.is_empty() {
137        return Err(WebhookParseError {
138            kind: WebhookParseErrorType::SegmentMissing,
139            source: None,
140        });
141    }
142
143    let id = id_segment
144        .parse::<NonZeroU64>()
145        .map_err(|source| WebhookParseError {
146            kind: WebhookParseErrorType::IdInvalid,
147            source: Some(Box::new(source)),
148        })?;
149    let mut token = segments.next();
150
151    // Don't return an empty token if the segment is empty.
152    if token.is_some_and(str::is_empty) {
153        token = None;
154    }
155
156    Ok((Id::from(id), token))
157}
158
159#[cfg(test)]
160mod tests {
161    use super::{WebhookParseError, WebhookParseErrorType};
162    use static_assertions::assert_impl_all;
163    use std::{error::Error, fmt::Debug};
164    use twilight_model::id::Id;
165
166    assert_impl_all!(WebhookParseErrorType: Debug, Send, Sync);
167    assert_impl_all!(WebhookParseError: Debug, Error, Send, Sync);
168
169    #[test]
170    fn parse_no_token() {
171        assert_eq!(
172            (Id::new(123), None),
173            super::parse("https://discord.com/api/webhooks/123").unwrap(),
174        );
175        // There's a / after the ID signifying another segment, but the token
176        // ends up being None.
177        assert_eq!(
178            (Id::new(123), None),
179            super::parse("https://discord.com/api/webhooks/123").unwrap(),
180        );
181        assert!(super::parse("https://discord.com/api/webhooks/123/")
182            .unwrap()
183            .1
184            .is_none());
185    }
186
187    #[test]
188    fn parse_with_token() {
189        assert_eq!(
190            super::parse("https://discord.com/api/webhooks/456/token").unwrap(),
191            (Id::new(456), Some("token")),
192        );
193        // The value of the segment(s) after the token are ignored.
194        assert_eq!(
195            super::parse("https://discord.com/api/webhooks/456/token/github").unwrap(),
196            (Id::new(456), Some("token")),
197        );
198        assert_eq!(
199            super::parse("https://discord.com/api/webhooks/456/token/slack").unwrap(),
200            (Id::new(456), Some("token")),
201        );
202        assert_eq!(
203            super::parse("https://discord.com/api/webhooks/456/token/randomsegment").unwrap(),
204            (Id::new(456), Some("token")),
205        );
206        assert_eq!(
207            super::parse("https://discord.com/api/webhooks/456/token/one/two/three").unwrap(),
208            (Id::new(456), Some("token")),
209        );
210    }
211
212    #[test]
213    fn parse_invalid() {
214        // Base URL is improper.
215        assert!(matches!(
216            super::parse("https://discord.com/foo/bar/456")
217                .unwrap_err()
218                .kind(),
219            &WebhookParseErrorType::SegmentMissing,
220        ));
221        // No ID is present.
222        assert!(matches!(
223            super::parse("https://discord.com/api/webhooks/")
224                .unwrap_err()
225                .kind(),
226            &WebhookParseErrorType::SegmentMissing,
227        ));
228        // ID segment isn't an integer.
229        assert!(matches!(
230            super::parse("https://discord.com/api/webhooks/notaninteger")
231                .unwrap_err()
232                .kind(),
233            &WebhookParseErrorType::IdInvalid { .. },
234        ));
235    }
236}
twilight_util/link/webhook.rs

twilight_util/link/
webhook.rs
