tokio_xmpp/
lib.rs

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_auto_cfg))]
75
76macro_rules! fail_native_with_any {
77    ($($feature:literal),+) => {
78        $(
79            #[cfg(all(
80                not(xmpprs_doc_build),
81                not(doc),
82                feature = "native-tls",
83                feature = $feature,
84            ))]
85            compile_error!(
86                concat!(
87                    "native-tls cannot be mixed with the ",
88                    $feature,
89                    " feature. Pick one or the other."
90                )
91            );
92        )+
93    }
94}
95
96fail_native_with_any!("ring", "aws_lc_rs", "ktls", "rustls-any-backend");
97
98#[cfg(all(
99    feature = "starttls",
100    not(feature = "native-tls"),
101    not(any(feature = "rustls-any-backend"))
102))]
103compile_error!(
104    "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."
105);
106
107extern crate alloc;
108
109pub use parsers::{jid, minidom};
110pub use xmpp_parsers as parsers;
111
112#[cfg(any(feature = "ring", feature = "aws_lc_rs", feature = "ktls"))]
113pub use tokio_rustls::rustls;
114
115mod client;
116#[cfg(feature = "insecure-tcp")]
117mod component;
118pub mod connect;
119/// Detailed error types
120pub mod error;
121mod event;
122pub mod stanzastream;
123pub mod xmlstream;
124
125#[doc(inline)]
126/// Generic tokio_xmpp Error
127pub use crate::error::Error;
128pub use client::{Client, IqFailure, IqRequest, IqResponse, IqResponseToken};
129#[cfg(feature = "insecure-tcp")]
130pub use component::Component;
131pub use event::{Event, Stanza};
132
133#[cfg(test)]
134mod tests {
135    #[test]
136    fn reexports() {
137        #[allow(unused_imports)]
138        use crate::jid;
139        #[allow(unused_imports)]
140        use crate::minidom;
141        #[allow(unused_imports)]
142        use crate::parsers;
143    }
144}
145
146// Re-export for debug purposes
147pub use xso::asxml::PrintRawXml;
tokio_xmpp/lib.rs

tokio_xmpp/
lib.rs
