xmpp_parsers/
stanza_error.rs

1// Copyright (c) 2017 Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
2//
3// This Source Code Form is subject to the terms of the Mozilla Public
4// License, v. 2.0. If a copy of the MPL was not distributed with this
5// file, You can obtain one at http://mozilla.org/MPL/2.0/.
6
7use xso::{text::EmptyAsNone, AsXml, FromXml};
8
9use crate::message::MessagePayload;
10use crate::ns;
11use crate::presence::PresencePayload;
12use alloc::collections::BTreeMap;
13use core::convert::TryFrom;
14use jid::Jid;
15use minidom::Element;
16use xso::error::{Error, FromElementError};
17
18generate_attribute!(
19    /// The type of the error.
20    ErrorType, "type", {
21        /// Retry after providing credentials.
22        Auth => "auth",
23
24        /// Do not retry (the error cannot be remedied).
25        Cancel => "cancel",
26
27        /// Proceed (the condition was only a warning).
28        Continue => "continue",
29
30        /// Retry after changing the data sent.
31        Modify => "modify",
32
33        /// Retry after waiting (the error is temporary).
34        Wait => "wait",
35    }
36);
37
38/// List of valid error conditions.
39#[derive(FromXml, AsXml, PartialEq, Debug, Clone)]
40#[xml(namespace = ns::XMPP_STANZAS, exhaustive)]
41pub enum DefinedCondition {
42    /// The sender has sent a stanza containing XML that does not conform
43    /// to the appropriate schema or that cannot be processed (e.g., an IQ
44    /// stanza that includes an unrecognized value of the 'type' attribute,
45    /// or an element that is qualified by a recognized namespace but that
46    /// violates the defined syntax for the element); the associated error
47    /// type SHOULD be "modify".
48    #[xml(name = "bad-request")]
49    BadRequest,
50
51    /// Access cannot be granted because an existing resource exists with
52    /// the same name or address; the associated error type SHOULD be
53    /// "cancel".
54    #[xml(name = "conflict")]
55    Conflict,
56
57    /// The feature represented in the XML stanza is not implemented by the
58    /// intended recipient or an intermediate server and therefore the
59    /// stanza cannot be processed (e.g., the entity understands the
60    /// namespace but does not recognize the element name); the associated
61    /// error type SHOULD be "cancel" or "modify".
62    #[xml(name = "feature-not-implemented")]
63    FeatureNotImplemented,
64
65    /// The requesting entity does not possess the necessary permissions to
66    /// perform an action that only certain authorized roles or individuals
67    /// are allowed to complete (i.e., it typically relates to
68    /// authorization rather than authentication); the associated error
69    /// type SHOULD be "auth".
70    #[xml(name = "forbidden")]
71    Forbidden,
72
73    /// The recipient or server can no longer be contacted at this address,
74    /// typically on a permanent basis (as opposed to the \<redirect/\> error
75    /// condition, which is used for temporary addressing failures); the
76    /// associated error type SHOULD be "cancel" and the error stanza
77    /// SHOULD include a new address (if available) as the XML character
78    /// data of the \<gone/\> element (which MUST be a Uniform Resource
79    /// Identifier (URI) or Internationalized Resource Identifier (IRI) at
80    /// which the entity can be contacted, typically an XMPP IRI as
81    /// specified in [XMPP‑URI](https://www.rfc-editor.org/rfc/rfc5122)).
82    #[xml(name = "gone")]
83    Gone {
84        /// The new address of the entity for which the error was returned,
85        /// if available.
86        #[xml(text(codec = EmptyAsNone))]
87        new_address: Option<String>,
88    },
89
90    /// The server has experienced a misconfiguration or other internal
91    /// error that prevents it from processing the stanza; the associated
92    /// error type SHOULD be "cancel".
93    #[xml(name = "internal-server-error")]
94    InternalServerError,
95
96    /// The addressed JID or item requested cannot be found; the associated
97    /// error type SHOULD be "cancel".
98    #[xml(name = "item-not-found")]
99    ItemNotFound,
100
101    /// The sending entity has provided (e.g., during resource binding) or
102    /// communicated (e.g., in the 'to' address of a stanza) an XMPP
103    /// address or aspect thereof that violates the rules defined in
104    /// [XMPP‑ADDR]; the associated error type SHOULD be "modify".
105    #[xml(name = "jid-malformed")]
106    JidMalformed,
107
108    /// The recipient or server understands the request but cannot process
109    /// it because the request does not meet criteria defined by the
110    /// recipient or server (e.g., a request to subscribe to information
111    /// that does not simultaneously include configuration parameters
112    /// needed by the recipient); the associated error type SHOULD be
113    /// "modify".
114    #[xml(name = "not-acceptable")]
115    NotAcceptable,
116
117    /// The recipient or server does not allow any entity to perform the
118    /// action (e.g., sending to entities at a blacklisted domain); the
119    /// associated error type SHOULD be "cancel".
120    #[xml(name = "not-allowed")]
121    NotAllowed,
122
123    /// The sender needs to provide credentials before being allowed to
124    /// perform the action, or has provided improper credentials (the name
125    /// "not-authorized", which was borrowed from the "401 Unauthorized"
126    /// error of HTTP, might lead the reader to think that this condition
127    /// relates to authorization, but instead it is typically used in
128    /// relation to authentication); the associated error type SHOULD be
129    /// "auth".
130    #[xml(name = "not-authorized")]
131    NotAuthorized,
132
133    /// The entity has violated some local service policy (e.g., a message
134    /// contains words that are prohibited by the service) and the server
135    /// MAY choose to specify the policy in the \<text/\> element or in an
136    /// application-specific condition element; the associated error type
137    /// SHOULD be "modify" or "wait" depending on the policy being
138    /// violated.
139    #[xml(name = "policy-violation")]
140    PolicyViolation,
141
142    /// The intended recipient is temporarily unavailable, undergoing
143    /// maintenance, etc.; the associated error type SHOULD be "wait".
144    #[xml(name = "recipient-unavailable")]
145    RecipientUnavailable,
146
147    /// The recipient or server is redirecting requests for this
148    /// information to another entity, typically in a temporary fashion (as
149    /// opposed to the \<gone/\> error condition, which is used for permanent
150    /// addressing failures); the associated error type SHOULD be "modify"
151    /// and the error stanza SHOULD contain the alternate address in the
152    /// XML character data of the \<redirect/\> element (which MUST be a URI
153    /// or IRI with which the sender can communicate, typically an XMPP IRI
154    /// as specified in [XMPP‑URI](https://xmpp.org/rfcs/rfc5122.html)).
155    #[xml(name = "redirect")]
156    Redirect {
157        /// The new address of the entity for which the error was returned,
158        /// if available.
159        #[xml(text(codec = EmptyAsNone))]
160        new_address: Option<String>,
161    },
162
163    /// The requesting entity is not authorized to access the requested
164    /// service because prior registration is necessary (examples of prior
165    /// registration include members-only rooms in XMPP multi-user chat
166    /// [XEP‑0045] and gateways to non-XMPP instant messaging services,
167    /// which traditionally required registration in order to use the
168    /// gateway [XEP‑0100]); the associated error type SHOULD be "auth".
169    #[xml(name = "registration-required")]
170    RegistrationRequired,
171
172    /// A remote server or service specified as part or all of the JID of
173    /// the intended recipient does not exist or cannot be resolved (e.g.,
174    /// there is no _xmpp-server._tcp DNS SRV record, the A or AAAA
175    /// fallback resolution fails, or A/AAAA lookups succeed but there is
176    /// no response on the IANA-registered port 5269); the associated error
177    /// type SHOULD be "cancel".
178    #[xml(name = "remote-server-not-found")]
179    RemoteServerNotFound,
180
181    /// A remote server or service specified as part or all of the JID of
182    /// the intended recipient (or needed to fulfill a request) was
183    /// resolved but communications could not be established within a
184    /// reasonable amount of time (e.g., an XML stream cannot be
185    /// established at the resolved IP address and port, or an XML stream
186    /// can be established but stream negotiation fails because of problems
187    /// with TLS, SASL, Server Dialback, etc.); the associated error type
188    /// SHOULD be "wait" (unless the error is of a more permanent nature,
189    /// e.g., the remote server is found but it cannot be authenticated or
190    /// it violates security policies).
191    #[xml(name = "remote-server-timeout")]
192    RemoteServerTimeout,
193
194    /// The server or recipient is busy or lacks the system resources
195    /// necessary to service the request; the associated error type SHOULD
196    /// be "wait".
197    #[xml(name = "resource-constraint")]
198    ResourceConstraint,
199
200    /// The server or recipient does not currently provide the requested
201    /// service; the associated error type SHOULD be "cancel".
202    #[xml(name = "service-unavailable")]
203    ServiceUnavailable,
204
205    /// The requesting entity is not authorized to access the requested
206    /// service because a prior subscription is necessary (examples of
207    /// prior subscription include authorization to receive presence
208    /// information as defined in [XMPP‑IM] and opt-in data feeds for XMPP
209    /// publish-subscribe as defined in [XEP‑0060]); the associated error
210    /// type SHOULD be "auth".
211    #[xml(name = "subscription-required")]
212    SubscriptionRequired,
213
214    /// The error condition is not one of those defined by the other
215    /// conditions in this list; any error type can be associated with this
216    /// condition, and it SHOULD NOT be used except in conjunction with an
217    /// application-specific condition.
218    #[xml(name = "undefined-condition")]
219    UndefinedCondition,
220
221    /// The recipient or server understood the request but was not
222    /// expecting it at this time (e.g., the request was out of order); the
223    /// associated error type SHOULD be "wait" or "modify".
224    #[xml(name = "unexpected-request")]
225    UnexpectedRequest,
226}
227
228type Lang = String;
229
230/// The representation of a stanza error.
231#[derive(Debug, Clone, PartialEq)]
232pub struct StanzaError {
233    /// The type of this error.
234    pub type_: ErrorType,
235
236    /// The JID of the entity who set this error.
237    pub by: Option<Jid>,
238
239    /// One of the defined conditions for this error to happen.
240    pub defined_condition: DefinedCondition,
241
242    /// Human-readable description of this error.
243    pub texts: BTreeMap<Lang, String>,
244
245    /// A protocol-specific extension for this error.
246    pub other: Option<Element>,
247}
248
249impl MessagePayload for StanzaError {}
250impl PresencePayload for StanzaError {}
251
252impl StanzaError {
253    /// Create a new `<error/>` with the according content.
254    pub fn new<L, T>(
255        type_: ErrorType,
256        defined_condition: DefinedCondition,
257        lang: L,
258        text: T,
259    ) -> StanzaError
260    where
261        L: Into<Lang>,
262        T: Into<String>,
263    {
264        StanzaError {
265            type_,
266            by: None,
267            defined_condition,
268            texts: {
269                let mut map = BTreeMap::new();
270                map.insert(lang.into(), text.into());
271                map
272            },
273            other: None,
274        }
275    }
276}
277
278impl TryFrom<Element> for StanzaError {
279    type Error = FromElementError;
280
281    fn try_from(elem: Element) -> Result<StanzaError, FromElementError> {
282        check_self!(elem, "error", DEFAULT_NS);
283        // The code attribute has been deprecated in [XEP-0086](https://xmpp.org/extensions/xep-0086.html)
284        // which was deprecated in 2007. We don't error when it's here, but don't include it in the final struct.
285        check_no_unknown_attributes!(elem, "error", ["type", "by", "code"]);
286
287        let mut stanza_error = StanzaError {
288            type_: get_attr!(elem, "type", Required),
289            by: get_attr!(elem, "by", Option),
290            defined_condition: DefinedCondition::UndefinedCondition,
291            texts: BTreeMap::new(),
292            other: None,
293        };
294        let mut defined_condition = None;
295
296        for child in elem.children() {
297            if child.is("text", ns::XMPP_STANZAS) {
298                check_no_children!(child, "text");
299                check_no_unknown_attributes!(child, "text", ["xml:lang"]);
300                let lang = get_attr!(child, "xml:lang", Default);
301                if stanza_error.texts.insert(lang, child.text()).is_some() {
302                    return Err(
303                        Error::Other("Text element present twice for the same xml:lang.").into(),
304                    );
305                }
306            } else if child.has_ns(ns::XMPP_STANZAS) {
307                if defined_condition.is_some() {
308                    return Err(Error::Other(
309                        "Error must not have more than one defined-condition.",
310                    )
311                    .into());
312                }
313                check_no_children!(child, "defined-condition");
314                check_no_attributes!(child, "defined-condition");
315                defined_condition = Some(DefinedCondition::try_from(child.clone())?);
316            } else {
317                if stanza_error.other.is_some() {
318                    return Err(
319                        Error::Other("Error must not have more than one other element.").into(),
320                    );
321                }
322                stanza_error.other = Some(child.clone());
323            }
324        }
325        stanza_error.defined_condition =
326            defined_condition.ok_or(Error::Other("Error must have a defined-condition."))?;
327
328        Ok(stanza_error)
329    }
330}
331
332impl From<StanzaError> for Element {
333    fn from(err: StanzaError) -> Element {
334        Element::builder("error", ns::DEFAULT_NS)
335            .attr("type", err.type_)
336            .attr("by", err.by)
337            .append(err.defined_condition)
338            .append_all(err.texts.into_iter().map(|(lang, text)| {
339                Element::builder("text", ns::XMPP_STANZAS)
340                    .attr("xml:lang", lang)
341                    .append(text)
342            }))
343            .append_all(err.other)
344            .build()
345    }
346}
347
348#[cfg(test)]
349mod tests {
350    use super::*;
351
352    #[cfg(target_pointer_width = "32")]
353    #[test]
354    fn test_size() {
355        assert_size!(ErrorType, 1);
356        assert_size!(DefinedCondition, 16);
357        assert_size!(StanzaError, 108);
358    }
359
360    #[cfg(target_pointer_width = "64")]
361    #[test]
362    fn test_size() {
363        assert_size!(ErrorType, 1);
364        assert_size!(DefinedCondition, 32);
365        assert_size!(StanzaError, 216);
366    }
367
368    #[test]
369    fn test_simple() {
370        #[cfg(not(feature = "component"))]
371        let elem: Element = "<error xmlns='jabber:client' type='cancel'><undefined-condition xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/></error>".parse().unwrap();
372        #[cfg(feature = "component")]
373        let elem: Element = "<error xmlns='jabber:component:accept' type='cancel'><undefined-condition xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/></error>".parse().unwrap();
374        let error = StanzaError::try_from(elem).unwrap();
375        assert_eq!(error.type_, ErrorType::Cancel);
376        assert_eq!(
377            error.defined_condition,
378            DefinedCondition::UndefinedCondition
379        );
380    }
381
382    #[test]
383    fn test_invalid_type() {
384        #[cfg(not(feature = "component"))]
385        let elem: Element = "<error xmlns='jabber:client'/>".parse().unwrap();
386        #[cfg(feature = "component")]
387        let elem: Element = "<error xmlns='jabber:component:accept'/>".parse().unwrap();
388        let error = StanzaError::try_from(elem).unwrap_err();
389        let message = match error {
390            FromElementError::Invalid(Error::Other(string)) => string,
391            _ => panic!(),
392        };
393        assert_eq!(message, "Required attribute 'type' missing.");
394
395        #[cfg(not(feature = "component"))]
396        let elem: Element = "<error xmlns='jabber:client' type='coucou'/>"
397            .parse()
398            .unwrap();
399        #[cfg(feature = "component")]
400        let elem: Element = "<error xmlns='jabber:component:accept' type='coucou'/>"
401            .parse()
402            .unwrap();
403        let error = StanzaError::try_from(elem).unwrap_err();
404        let message = match error {
405            FromElementError::Invalid(Error::TextParseError(string)) => string,
406            _ => panic!(),
407        };
408        assert_eq!(message.to_string(), "Unknown value for 'type' attribute.");
409    }
410
411    #[test]
412    fn test_invalid_condition() {
413        #[cfg(not(feature = "component"))]
414        let elem: Element = "<error xmlns='jabber:client' type='cancel'/>"
415            .parse()
416            .unwrap();
417        #[cfg(feature = "component")]
418        let elem: Element = "<error xmlns='jabber:component:accept' type='cancel'/>"
419            .parse()
420            .unwrap();
421        let error = StanzaError::try_from(elem).unwrap_err();
422        let message = match error {
423            FromElementError::Invalid(Error::Other(string)) => string,
424            _ => panic!(),
425        };
426        assert_eq!(message, "Error must have a defined-condition.");
427    }
428
429    #[test]
430    fn test_error_code() {
431        let elem: Element = r#"<error code="501" type="cancel" xmlns='jabber:client'>
432    <feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
433    <text xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'>The feature requested is not implemented by the recipient or server and therefore cannot be processed.</text>
434</error>"#
435            .parse()
436            .unwrap();
437        let stanza_error = StanzaError::try_from(elem).unwrap();
438        assert_eq!(stanza_error.type_, ErrorType::Cancel);
439    }
440
441    #[test]
442    fn test_error_multiple_text() {
443        let elem: Element = r#"<error type="cancel" xmlns='jabber:client'>
444    <item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
445    <text xmlns='urn:ietf:params:xml:ns:xmpp-stanzas' xml:lang="fr">Nœud non trouvé</text>
446    <text xmlns='urn:ietf:params:xml:ns:xmpp-stanzas' xml:lang="en">Node not found</text>
447</error>"#
448            .parse()
449            .unwrap();
450        let stanza_error = StanzaError::try_from(elem).unwrap();
451        assert_eq!(stanza_error.type_, ErrorType::Cancel);
452    }
453
454    #[test]
455    fn test_gone_with_new_address() {
456        #[cfg(not(feature = "component"))]
457            let elem: Element = "<error xmlns='jabber:client' type='cancel'><gone xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'>xmpp:room@muc.example.org?join</gone></error>"
458            .parse()
459            .unwrap();
460        #[cfg(feature = "component")]
461            let elem: Element = "<error xmlns='jabber:component:accept' type='cancel'><gone xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'>xmpp:room@muc.example.org?join</gone></error>"
462            .parse()
463            .unwrap();
464        let error = StanzaError::try_from(elem).unwrap();
465        assert_eq!(error.type_, ErrorType::Cancel);
466        assert_eq!(
467            error.defined_condition,
468            DefinedCondition::Gone {
469                new_address: Some("xmpp:room@muc.example.org?join".to_string()),
470            }
471        );
472    }
473
474    #[test]
475    fn test_gone_without_new_address() {
476        #[cfg(not(feature = "component"))]
477            let elem: Element = "<error xmlns='jabber:client' type='cancel'><gone xmlns='urn:ietf:params:xml:ns:xmpp-stanzas' /></error>"
478            .parse()
479            .unwrap();
480        #[cfg(feature = "component")]
481            let elem: Element = "<error xmlns='jabber:component:accept' type='cancel'><gone xmlns='urn:ietf:params:xml:ns:xmpp-stanzas' /></error>"
482            .parse()
483            .unwrap();
484        let error = StanzaError::try_from(elem).unwrap();
485        assert_eq!(error.type_, ErrorType::Cancel);
486        assert_eq!(
487            error.defined_condition,
488            DefinedCondition::Gone { new_address: None }
489        );
490    }
491
492    #[test]
493    fn test_redirect_with_alternate_address() {
494        #[cfg(not(feature = "component"))]
495            let elem: Element = "<error xmlns='jabber:client' type='modify'><redirect xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'>xmpp:characters@conference.example.org</redirect></error>"
496            .parse()
497            .unwrap();
498        #[cfg(feature = "component")]
499            let elem: Element = "<error xmlns='jabber:component:accept' type='modify'><redirect xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'>xmpp:characters@conference.example.org</redirect></error>"
500            .parse()
501            .unwrap();
502        let error = StanzaError::try_from(elem).unwrap();
503        assert_eq!(error.type_, ErrorType::Modify);
504        assert_eq!(
505            error.defined_condition,
506            DefinedCondition::Redirect {
507                new_address: Some("xmpp:characters@conference.example.org".to_string()),
508            }
509        );
510    }
511
512    #[test]
513    fn test_redirect_without_alternate_address() {
514        #[cfg(not(feature = "component"))]
515            let elem: Element = "<error xmlns='jabber:client' type='modify'><redirect xmlns='urn:ietf:params:xml:ns:xmpp-stanzas' /></error>"
516            .parse()
517            .unwrap();
518        #[cfg(feature = "component")]
519            let elem: Element = "<error xmlns='jabber:component:accept' type='modify'><redirect xmlns='urn:ietf:params:xml:ns:xmpp-stanzas' /></error>"
520            .parse()
521            .unwrap();
522        let error = StanzaError::try_from(elem).unwrap();
523        assert_eq!(error.type_, ErrorType::Modify);
524        assert_eq!(
525            error.defined_condition,
526            DefinedCondition::Redirect { new_address: None }
527        );
528    }
529}
xmpp_parsers/stanza_error.rs

xmpp_parsers/
stanza_error.rs
