1//! Low-level [XMPP](https://xmpp.org/) decentralized instant messaging & social networking implementation with asynchronous I/O using [tokio](https://tokio.rs/).
2//!
3//! For an easier, batteries-included experience, try the [xmpp crate](https://docs.rs/xmpp).
4//!
5//! # Getting started
6//!
7//! In most cases, you want to start with a [`Client`], that will connect to a server over TCP/IP with StartTLS encryption. Then, you can build an event loop by calling the client's `next` method repeatedly. You can find a more complete example in the [examples/echo_bot.rs](https://gitlab.com/xmpp-rs/xmpp-rs/-/blob/main/tokio-xmpp/examples/echo_bot.rs) file in the repository.
8//!
9//! # Features
10//!
11//! This library is not feature-complete yet. Here's a quick overview of the feature set.
12//!
13//! Supported implementations:
14//! - [x] Clients
15//! - [x] Components
16//! - [ ] Servers
17//!
18//! Supported transports:
19//! - [x] Plaintext TCP (IPv4/IPv6)
20//! - [x] StartTLS TCP (IPv4/IPv6 with [happy eyeballs](https://en.wikipedia.org/wiki/Happy_Eyeballs) support)
21//! - [x] Custom connectors via the [`connect::ServerConnector`] trait
22//! - [ ] Websockets
23//! - [ ] BOSH
24//!
25//! # Cargo features
26//!
27//! ## TLS backends
28//!
29//! - `aws_lc_rs` (default) enables rustls with the `aws_lc_rs` backend.
30//! - `ring` enables rustls with the `ring` backend`.
31//! - `rustls-any-backend` enables rustls, but without enabling a backend. It
32//! is the application's responsibility to ensure that a backend is enabled
33//! and installed.
34//! - `ktls` enables the use of ktls.
35//! **Important:** Currently, connections will fail if the `tls` kernel
36//! module is not available. There is no fallback to non-ktls connections!
37//! - `native-tls` enables the system-native TLS library (commonly
38//! libssl/OpenSSL).
39//!
40//! **Note:** It is not allowed to mix rustls-based TLS backends with
41//! `tls-native`. Attempting to do so will result in a compilation error.
42//!
43//! **Note:** The `ktls` feature requires at least one `rustls` backend to be
44//! enabled (`aws_lc_rs` or `ring`).
45//!
46//! **Note:** When enabling not exactly one rustls backend, it is the
47//! application's responsibility to make sure that a default crypto provider is
48//! installed in `rustls`. Otherwise, all TLS connections will fail.
49//!
50//! ## Certificate validation
51//!
52//! When using `native-tls`, the system's native certificate store is used.
53//! Otherwise, you need to pick one of the following to ensure that TLS
54//! connections will succeed:
55//!
56//! - `rustls-native-certs` (default): Uses [rustls-native-certs](https://crates.io/crates/rustls-native-certs).
57//! - `webpki-roots`: Uses [webpki-roots](https://crates.io/crates/webpki-roots).
58//!
59//! ## Other features
60//!
61//! - `starttls` (default): Enables support for `<starttls/>`. Required as per
62//! RFC 6120.
63//! - `insecure-tcp`: Allow the use of insecure TCP connections to connect to
64//! XMPP servers. Required for XMPP components, but disabled by default to
65//! prevent accidental use.
66//! - `serde`: Enable the `serde` feature in `xmpp-parsers`.
67//! - `component`: Enable component support (implies `insecure-tcp`).
68//!
69//! # More information
70//!
71//! You can find more information on our website [xmpp.rs](https://xmpp.rs/) or by joining our chatroom [chat@xmpp.rs](xmpp:chat@xmpp.rs?join).
72
73#![deny(unsafe_code, missing_docs, bare_trait_objects)]
74#![cfg_attr(docsrs, feature(doc_cfg))]
75#![cfg_attr(docsrs, doc(auto_cfg))]
76
77macro_rules! fail_native_with_any {
78 ($($feature:literal),+) => {
79 $(
80 #[cfg(all(
81 not(xmpprs_doc_build),
82 not(doc),
83 feature = "native-tls",
84 feature = $feature,
85 ))]
86 compile_error!(
87 concat!(
88 "native-tls cannot be mixed with the ",
89 $feature,
90 " feature. Pick one or the other."
91 )
92 );
93 )+
94 }
95}
96
97fail_native_with_any!("ring", "aws_lc_rs", "ktls", "rustls-any-backend");
98
99#[cfg(all(
100 feature = "starttls",
101 not(feature = "native-tls"),
102 not(any(feature = "rustls-any-backend"))
103))]
104compile_error!(
105 "When the starttls feature is enabled, either native-tls or any of the rustls (aws_lc_rs, ring, or rustls-any-backend) features must be enabled."
106);
107
108extern crate alloc;
109
110pub use parsers::{jid, minidom};
111pub use xmpp_parsers as parsers;
112
113#[cfg(any(feature = "ring", feature = "aws_lc_rs", feature = "ktls"))]
114pub use tokio_rustls::rustls;
115
116mod client;
117#[cfg(feature = "insecure-tcp")]
118mod component;
119pub mod connect;
120/// Detailed error types
121pub mod error;
122mod event;
123pub mod stanzastream;
124pub mod xmlstream;
125
126pub use xso::{asxml::PrintRawXml, error::FromElementError};
127
128#[doc(inline)]
129/// Generic tokio_xmpp Error
130pub use crate::error::Error;
131pub use client::{Client, IqFailure, IqRequest, IqResponse, IqResponseToken};
132#[cfg(feature = "insecure-tcp")]
133pub use component::Component;
134pub use event::{Event, Stanza};
135
136#[cfg(test)]
137mod tests {
138 #[test]
139 fn reexports() {
140 #[allow(unused_imports)]
141 use crate::jid;
142 #[allow(unused_imports)]
143 use crate::minidom;
144 #[allow(unused_imports)]
145 use crate::parsers;
146 }
147}