xmpp-rs/parsers/src/stream_error.rs
2025-08-07 12:43:21 +00:00

516 lines
22 KiB
Rust

// Copyright (c) 2024 Jonas Schäfer <jonas@zombofant.net>
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at http://mozilla.org/MPL/2.0/.
use alloc::collections::BTreeMap;
use core::{error::Error, fmt};
use minidom::Element;
use xso::{AsXml, FromXml};
use crate::{message::Lang, ns};
/// Enumeration of all stream error conditions as defined in [RFC 6120].
///
/// All variant documentation is directly quoted from [RFC 6120].
///
/// [RFC 6120]: https://datatracker.ietf.org/doc/html/rfc6120#section-4.9.3
#[derive(FromXml, AsXml, PartialEq, Debug, Clone)]
#[xml(namespace = ns::XMPP_STREAMS)]
pub enum DefinedCondition {
/// The entity has sent XML that cannot be processed.
///
/// This error can be used instead of the more specific XML-related
/// errors, such as `<bad-namespace-prefix/>`, `<invalid-xml/>`,
/// `<not-well-formed/>`, `<restricted-xml/>`, and
/// `<unsupported-encoding/>`. However, the more specific errors are
/// RECOMMENDED.
#[xml(name = "bad-format")]
BadFormat,
/// The entity has sent a namespace prefix that is unsupported, or has
/// sent no namespace prefix on an element that needs such a prefix (see
/// [Section 11.2](https://datatracker.ietf.org/doc/html/rfc6120#section-11.2)).
#[xml(name = "bad-namespace-prefix")]
BadNamespacePrefix,
/// The server either (1) is closing the existing stream for this entity
/// because a new stream has been initiated that conflicts with the
/// existing stream, or (2) is refusing a new stream for this entity
/// because allowing the new stream would conflict with an existing
/// stream (e.g., because the server allows only a certain number of
/// connections from the same IP address or allows only one server-to-
/// server stream for a given domain pair as a way of helping to ensure
/// in-order processing as described under
/// [Section 10.1](https://datatracker.ietf.org/doc/html/rfc6120#section-10.1)).
///
/// If a client receives a `<conflict/>` stream error, during the resource
/// binding aspect of its reconnection attempt it MUST NOT blindly request
/// the resourcepart it used during the former session but instead MUST
/// choose a different resourcepart; details are provided under
/// [Section 7](https://datatracker.ietf.org/doc/html/rfc6120#section-7).
#[xml(name = "conflict")]
Conflict,
/// One party is closing the stream because it has reason to believe that
/// the other party has permanently lost the ability to communicate over
/// the stream. The lack of ability to communicate can be discovered
/// using various methods, such as whitespace keepalives as specified
/// under
/// [Section 4.4](https://datatracker.ietf.org/doc/html/rfc6120#section-4.4),
/// XMPP-level pings as defined in
/// [XEP-0199](https://xmpp.org/extensions/xep-0199.html), and
/// XMPP Stream Management as defined in
/// [XEP-0198](https://xmpp.org/extensions/xep-0198.html).
///
/// Interoperability Note: RFC 3920 specified that the
/// `<connection-timeout/>` stream error is to be used if the peer has not
/// generated any traffic over the stream for some period of time.
/// That behavior is no longer recommended; instead, the error SHOULD be
/// used only if the connected client or peer server has not responded to
/// data sent over the stream.
#[xml(name = "connection-timeout")]
ConnectionTimeout,
/// The value of the 'to' attribute provided in the initial stream header
/// corresponds to an FQDN that is no longer serviced by the receiving
/// entity.
#[xml(name = "host-gone")]
HostGone,
/// The value of the 'to' attribute provided in the initial stream header
/// does not correspond to an FQDN that is serviced by the receiving
/// entity.
#[xml(name = "host-unknown")]
HostUnknown,
/// A stanza sent between two servers lacks a 'to' or 'from' attribute,
/// the 'from' or 'to' attribute has no value, or the value violates the
/// rules for XMPP addresses
/// (see [RFC 6122](https://datatracker.ietf.org/doc/html/rfc6122)).
#[xml(name = "improper-addressing")]
ImproperAddressing,
/// The server has experienced a misconfiguration or other internal error
/// that prevents it from servicing the stream.
#[xml(name = "internal-server-error")]
InternalServerError,
/// The data provided in a 'from' attribute does not match an authorized
/// JID or validated domain as negotiated (1) between two servers using
/// SASL or Server Dialback, or (2) between a client and a server via
/// SASL authentication and resource binding.
#[xml(name = "invalid-from")]
InvalidFrom,
/// The stream namespace name is something other than
/// `http://etherx.jabber.org/streams` (see
/// [Section 11.2](https://datatracker.ietf.org/doc/html/rfc6120#section-11.2))
/// or the content namespace declared as the default namespace is not
/// supported (e.g., something other than `jabber:client` or
/// `jabber:server`).
#[xml(name = "invalid-namespace")]
InvalidNamespace,
/// The entity has sent invalid XML over the stream to a server that
/// performs validation (see
/// [Section 11.4](https://datatracker.ietf.org/doc/html/rfc6120#section-11.4)).
#[xml(name = "invalid-xml")]
InvalidXml,
/// The entity has attempted to send XML stanzas or other outbound data
/// before the stream has been authenticated, or otherwise is not
/// authorized to perform an action related to stream negotiation; the
/// receiving entity MUST NOT process the offending data before sending
/// the stream error.
#[xml(name = "not-authorized")]
NotAuthorized,
/// The initiating entity has sent XML that violates the well-formedness
/// rules of [XML](https://www.w3.org/TR/REC-xml/) or
/// [XML-NAMES](https://www.w3.org/TR/REC-xml-names/).
#[xml(name = "not-well-formed")]
NotWellFormed,
/// The entity has violated some local service policy (e.g., a stanza
/// exceeds a configured size limit); the server MAY choose to specify
/// the policy in the `<text/>` element or in an application-specific
/// condition element.
#[xml(name = "policy-violation")]
PolicyViolation,
/// The server is unable to properly connect to a remote entity that is
/// needed for authentication or authorization (e.g., in certain
/// scenarios related to Server Dialback
/// [XEP-0220](https://xmpp.org/extensions/xep-0220.html)); this condition
/// is not to be used when the cause of the error is within the
/// administrative domain of the XMPP service provider, in which case the
/// `<internal-server-error/>` condition is more appropriate.
#[xml(name = "remote-connection-failed")]
RemoteConnectionFailed,
/// The server is closing the stream because it has new (typically
/// security-critical) features to offer, because the keys or
/// certificates used to establish a secure context for the stream have
/// expired or have been revoked during the life of the stream
/// ([Section 13.7.2.3](https://datatracker.ietf.org/doc/html/rfc6120#section-13.7.2.3)),
/// because the TLS sequence number has wrapped
/// ([Section 5.3.5](https://datatracker.ietf.org/doc/html/rfc6120#section-5.3.5)),
/// etc. The reset applies to the stream and to any security context
/// established for that stream (e.g., via TLS and SASL), which means that
/// encryption and authentication need to be negotiated again for the new
/// stream (e.g., TLS session resumption cannot be used).
#[xml(name = "reset")]
Reset,
/// The server lacks the system resources necessary to service the stream.
#[xml(name = "resource-constraint")]
ResourceConstraint,
/// The entity has attempted to send restricted XML features such as a
/// comment, processing instruction, DTD subset, or XML entity reference
/// (see
/// [Section 11.1](https://datatracker.ietf.org/doc/html/rfc6120#section-11.1)).
#[xml(name = "restricted-xml")]
RestrictedXml,
/// The server will not provide service to the initiating entity but is
/// redirecting traffic to another host under the administrative control
/// of the same service provider. The XML character data of the
/// `<see-other-host/>` element returned by the server MUST specify the
/// alternate FQDN or IP address at which to connect, which MUST be a
/// valid domainpart or a domainpart plus port number (separated by the
/// ':' character in the form "domainpart:port"). If the domainpart is
/// the same as the source domain, derived domain, or resolved IPv4 or
/// IPv6 address to which the initiating entity originally connected
/// (differing only by the port number), then the initiating entity
/// SHOULD simply attempt to reconnect at that address. (The format of
/// an IPv6 address MUST follow
/// [IPv6-ADDR](https://datatracker.ietf.org/doc/html/rfc6120#ref-IPv6-ADDR),
/// which includes the enclosing the IPv6 address in square brackets
/// '[' and ']' as originally defined by
/// [URI](https://datatracker.ietf.org/doc/html/rfc6120#ref-URI).
/// ) Otherwise, the initiating entity MUST resolve the FQDN
/// specified in the `<see-other-host/>` element as described under
/// [Section 3.2](https://datatracker.ietf.org/doc/html/rfc6120#section-3.2).
///
/// When negotiating a stream with the host to which it has been
/// redirected, the initiating entity MUST apply the same policies it
/// would have applied to the original connection attempt (e.g., a policy
/// requiring TLS), MUST specify the same 'to' address on the initial
/// stream header, and MUST verify the identity of the new host using the
/// same reference identifier(s) it would have used for the original
/// connection attempt (in accordance with
/// [TLS-CERTS](https://datatracker.ietf.org/doc/html/rfc6120#ref-TLS-CERTS)).
/// Even if the receiving entity returns a `<see-other-host/>` error
/// before the confidentiality and integrity of the stream have been
/// established (thus introducing the possibility of a denial-of-service
/// attack), the fact that the initiating entity needs to verify the
/// identity of the XMPP service based on the same reference identifiers
/// implies that the initiating entity will not connect to a malicious
/// entity. To reduce the possibility of a denial-of-service attack, (a)
/// the receiving entity SHOULD NOT close the stream with a
/// `<see-other-host/>` stream error until after the confidentiality and
/// integrity of the stream have been protected via TLS or an equivalent
/// security layer (such as the SASL GSSAPI mechanism), and (b) the
/// receiving entity MAY have a policy of following redirects only if it
/// has authenticated the receiving entity. In addition, the initiating
/// entity SHOULD abort the connection attempt after a certain number of
/// successive redirects (e.g., at least 2 but no more than 5).
#[xml(name = "see-other-host")]
SeeOtherHost(#[xml(text)] String),
/// The server is being shut down and all active streams are being closed.
#[xml(name = "system-shutdown")]
SystemShutdown,
/// The error condition is not one of those defined by the other
/// conditions in this list; this error condition SHOULD NOT be used
/// except in conjunction with an application-specific condition.
#[xml(name = "undefined-condition")]
UndefinedCondition,
/// The initiating entity has encoded the stream in an encoding that is
/// not supported by the server (see
/// [Section 11.6](https://datatracker.ietf.org/doc/html/rfc6120#section-11.6))
/// or has otherwise improperly encoded the stream (e.g., by violating the
/// rules of the
/// [UTF-8](https://datatracker.ietf.org/doc/html/rfc6120#ref-UTF-8)
/// encoding).
#[xml(name = "unsupported-encoding")]
UnsupportedEncoding,
/// The receiving entity has advertised a mandatory-to-negotiate stream
/// feature that the initiating entity does not support, and has offered
/// no other mandatory-to-negotiate feature alongside the unsupported
/// feature.
#[xml(name = "unsupported-feature")]
UnsupportedFeature,
/// The initiating entity has sent a first-level child of the stream that
/// is not supported by the server, either because the receiving entity
/// does not understand the namespace or because the receiving entity
/// does not understand the element name for the applicable namespace
/// (which might be the content namespace declared as the default
/// namespace).
#[xml(name = "unsupported-stanza-type")]
UnsupportedStanzaType,
/// The 'version' attribute provided by the initiating entity in the
/// stream header specifies a version of XMPP that is not supported by
/// the server.
#[xml(name = "unsupported-version")]
UnsupportedVersion,
}
impl fmt::Display for DefinedCondition {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
let s = match self {
Self::BadFormat => "bad-format",
Self::BadNamespacePrefix => "bad-namespace-prefix",
Self::Conflict => "conflict",
Self::ConnectionTimeout => "connection-timeout",
Self::HostGone => "host-gone",
Self::HostUnknown => "host-unknown",
Self::ImproperAddressing => "improper-addressing",
Self::InternalServerError => "internal-server-error",
Self::InvalidFrom => "invalid-from",
Self::InvalidNamespace => "invalid-namespace",
Self::InvalidXml => "invalid-xml",
Self::NotAuthorized => "not-authorized",
Self::NotWellFormed => "not-well-formed",
Self::PolicyViolation => "policy-violation",
Self::RemoteConnectionFailed => "remote-connection-failed",
Self::Reset => "reset",
Self::ResourceConstraint => "resource-constraint",
Self::RestrictedXml => "restricted-xml",
Self::SeeOtherHost(ref host) => return write!(f, "see-other-host: {}", host),
Self::SystemShutdown => "system-shutdown",
Self::UndefinedCondition => "undefined-condition",
Self::UnsupportedEncoding => "unsupported-encoding",
Self::UnsupportedFeature => "unsupported-feature",
Self::UnsupportedStanzaType => "unsupported-stanza-type",
Self::UnsupportedVersion => "unsupported-version",
};
f.write_str(s)
}
}
/// Stream error as specified in RFC 6120.
#[derive(FromXml, AsXml, PartialEq, Debug, Clone)]
#[xml(namespace = ns::STREAM, name = "error")]
pub struct StreamError {
/// The enumerated error condition which triggered this stream error.
#[xml(child)]
pub condition: DefinedCondition,
/// Optional error text
#[xml(extract(n = .., name = "text", namespace = ns::XMPP_STREAMS, fields(
lang(type_ = Lang, default),
text(type_ = String),
)))]
pub texts: BTreeMap<Lang, String>,
/// Optional application-defined element which refines the specified
/// [`Self::condition`].
// TODO: use n = 1 once we have it.
#[xml(element(n = ..))]
pub application_specific: Vec<Element>,
}
impl fmt::Display for StreamError {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
<DefinedCondition as fmt::Display>::fmt(&self.condition, f)?;
if let Some((_, text)) = self.get_best_text(vec!["en"]) {
write!(f, " ({:?})", text)?
}
if let Some(cond) = self.application_specific.first() {
f.write_str(&String::from(cond))?;
}
Ok(())
}
}
impl StreamError {
/// Create a new StreamError with condition, text, and language
pub fn new<S: Into<String>, L: Into<Lang>>(
condition: DefinedCondition,
lang: L,
text: S,
) -> Self {
let mut texts = BTreeMap::new();
texts.insert(lang.into(), text.into());
Self {
condition,
texts,
application_specific: Vec::new(),
}
}
/// Add a text element with the specified language
pub fn add_text<L: Into<Lang>, S: Into<String>>(mut self, lang: L, text: S) -> Self {
self.texts.insert(lang.into(), text.into());
self
}
/// Append application specific element(s)
pub fn with_application_specific(mut self, application_specific: Vec<Element>) -> Self {
self.application_specific = application_specific;
self
}
/// Get the best matching text from a list of preferred languages.
///
/// This follows the same logic as Message::get_best_body:
/// 1. First tries to find a match from the preferred languages list
/// 2. Falls back to empty language ("") if available
/// 3. Returns the first entry if no matches found
///
/// Returns None if no text elements exist.
pub fn get_best_text(&self, preferred_langs: Vec<&str>) -> Option<(Lang, &String)> {
Self::get_best(&self.texts, preferred_langs)
}
/// Cloned variant of [`StreamError::get_best_text`]
pub fn get_best_text_cloned(&self, preferred_langs: Vec<&str>) -> Option<(Lang, String)> {
Self::get_best_cloned(&self.texts, preferred_langs)
}
// Private helper methods matching Message's pattern
fn get_best<'a, T>(
map: &'a BTreeMap<Lang, T>,
preferred_langs: Vec<&str>,
) -> Option<(Lang, &'a T)> {
if map.is_empty() {
return None;
}
for lang in preferred_langs {
if let Some(value) = map.get(lang) {
return Some((Lang::from(lang), value));
}
}
if let Some(value) = map.get("") {
return Some((Lang::new(), value));
}
map.iter().map(|(lang, value)| (lang.clone(), value)).next()
}
fn get_best_cloned<T: ToOwned<Owned = T>>(
map: &BTreeMap<Lang, T>,
preferred_langs: Vec<&str>,
) -> Option<(Lang, T)> {
if let Some((lang, item)) = Self::get_best::<T>(map, preferred_langs) {
Some((lang, item.to_owned()))
} else {
None
}
}
/// Check if the error has any text elements
pub fn has_text(&self) -> bool {
!self.texts.is_empty()
}
}
/// Wrapper around [`StreamError`] which implements [`core::error::Error`]
/// with an appropriate error message.
#[derive(FromXml, AsXml, Debug)]
#[xml(transparent)]
pub struct ReceivedStreamError(pub StreamError);
impl fmt::Display for ReceivedStreamError {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
write!(f, "received stream error: {}", self.0)
}
}
impl Error for ReceivedStreamError {}
/// Wrapper around [`StreamError`] which implements [`core::error::Error`]
/// with an appropriate error message.
#[derive(FromXml, AsXml, Debug)]
#[xml(transparent)]
pub struct SentStreamError(pub StreamError);
impl fmt::Display for SentStreamError {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
write!(f, "sent stream error: {}", self.0)
}
}
impl Error for SentStreamError {}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn parses_condition_from_prosody() {
let doc = "<undefined-condition xmlns='urn:ietf:params:xml:ns:xmpp-streams'/>";
let err: DefinedCondition = xso::from_bytes(doc.as_bytes()).unwrap();
assert_eq!(err, DefinedCondition::UndefinedCondition);
}
#[test]
fn parses_stream_error_from_prosody() {
let doc = "<stream:error xmlns:stream='http://etherx.jabber.org/streams'><undefined-condition xmlns='urn:ietf:params:xml:ns:xmpp-streams'/><text xmlns='urn:ietf:params:xml:ns:xmpp-streams'>No stream features to proceed with</text></stream:error>";
let err: StreamError = xso::from_bytes(doc.as_bytes()).unwrap();
assert_eq!(err.condition, DefinedCondition::UndefinedCondition);
}
#[test]
fn test_stream_error_with_text() {
let doc = br#"<stream:error xmlns:stream='http://etherx.jabber.org/streams'>
<system-shutdown xmlns='urn:ietf:params:xml:ns:xmpp-streams'/>
<text xmlns='urn:ietf:params:xml:ns:xmpp-streams'>Server is shutting down for maintenance.</text>
</stream:error>"#;
let err: StreamError = xso::from_bytes(doc).unwrap();
assert_eq!(err.condition, DefinedCondition::SystemShutdown);
assert!(err.has_text());
let (lang, text) = err.get_best_text(vec![]).unwrap();
assert_eq!(text, "Server is shutting down for maintenance.");
assert_eq!(lang, "");
}
#[test]
fn test_stream_error_with_multiple_languages() {
let doc = br#"<stream:error xmlns:stream='http://etherx.jabber.org/streams'>
<policy-violation xmlns='urn:ietf:params:xml:ns:xmpp-streams'/>
<text xmlns='urn:ietf:params:xml:ns:xmpp-streams' xml:lang='en'>Message too large</text>
<text xmlns='urn:ietf:params:xml:ns:xmpp-streams' xml:lang='de'>Nachricht zu lang</text>
</stream:error>"#;
let err: StreamError = xso::from_bytes(doc).unwrap();
assert_eq!(err.condition, DefinedCondition::PolicyViolation);
// Test German preference
let (lang, text) = err.get_best_text(vec!["de"]).unwrap();
assert_eq!(lang, "de");
assert_eq!(text, "Nachricht zu lang");
// Test English preference
let (lang, text) = err.get_best_text(vec!["en"]).unwrap();
assert_eq!(lang, "en");
assert_eq!(text, "Message too large");
// Test cloned variant
let (lang, text) = err.get_best_text_cloned(vec!["en"]).unwrap();
assert_eq!(lang, "en");
assert_eq!(text, "Message too large");
}
#[test]
fn test_stream_error_constructors() {
let err = StreamError::new(DefinedCondition::Reset, "en", "Connection reset");
let (lang, text) = err.get_best_text(vec!["en"]).unwrap();
assert_eq!(lang, "en");
assert_eq!(text, "Connection reset");
let err = err.add_text("de", "Verbindung zurückgesetzt");
assert_eq!(err.texts.len(), 2);
}
}