1// Copyright (c) 2019 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//! # Cargo features
7//!
8//! ## TLS backends
9//!
10//! - `aws_lc_rs` (default) enables rustls with the `aws_lc_rs` backend.
11//! - `ring` enables rustls with the `ring` backend`.
12//! - `rustls-any-backend` enables rustls, but without enabling a backend. It
13//! is the application's responsibility to ensure that a backend is enabled
14//! and installed.
15//! - `ktls` enables the use of ktls.
16//! **Important:** Currently, connections will fail if the `tls` kernel
17//! module is not available. There is no fallback to non-ktls connections!
18//! - `native-tls` enables the system-native TLS library (commonly
19//! libssl/OpenSSL).
20//!
21//! **Note:** It is not allowed to mix rustls-based TLS backends with
22//! `tls-native`. Attempting to do so will result in a compilation error.
23//!
24//! **Note:** The `ktls` feature requires at least one `rustls` backend to be
25//! enabled (`aws_lc_rs` or `ring`).
26//!
27//! **Note:** When enabling not exactly one rustls backend, it is the
28//! application's responsibility to make sure that a default crypto provider is
29//! installed in `rustls`. Otherwise, all TLS connections will fail.
30//!
31//! ## Certificate validation
32//!
33//! When using `native-tls`, the system's native certificate store is used.
34//! Otherwise, you need to pick one of the following to ensure that TLS
35//! connections will succeed:
36//!
37//! - `rustls-native-certs` (default): Uses [rustls-native-certs](https://crates.io/crates/rustls-native-certs).
38//! - `webpki-roots`: Uses [webpki-roots](https://crates.io/crates/webpki-roots).
39//!
40//! ## Other features
41//!
42//! - `starttls` (default): Enables support for `<starttls/>`. Required as per
43//! RFC 6120.
44//! - `avatars` (default): Enables support for avatars.
45//! - `serde`: Enable the `serde` feature in `tokio-xmpp`.
46//! - `escape-hatch`: Allow access to low-level API to bypass shortcomings of the current API.
47
48#![deny(bare_trait_objects)]
49#![cfg_attr(docsrs, feature(doc_cfg))]
50#![cfg_attr(docsrs, doc(auto_cfg))]
51
52extern crate alloc;
53
54pub use tokio_xmpp;
55pub use tokio_xmpp::jid;
56pub use tokio_xmpp::minidom;
57pub use tokio_xmpp::parsers;
58
59#[macro_use]
60extern crate log;
61
62use core::fmt;
63use jid::{ResourcePart, ResourceRef};
64use parsers::message::Id as MessageId;
65
66pub mod agent;
67pub mod builder;
68#[cfg(feature = "component")]
69#[cfg(feature = "insecure-tcp")]
70pub mod component;
71pub mod config;
72pub mod delay;
73pub mod disco;
74pub mod event;
75pub mod event_loop;
76pub mod feature;
77pub mod iq;
78pub mod message;
79pub mod muc;
80pub mod presence;
81pub mod pubsub;
82pub mod upload;
83
84pub use agent::Agent;
85pub use builder::ClientBuilder;
86pub use config::{ClientType, Config};
87pub use event::Event;
88pub use feature::ClientFeature;
89
90pub type Error = tokio_xmpp::Error;
91
92/// Nickname for a person in a chatroom.
93///
94/// This nickname is not associated with a specific chatroom, or with a certain
95/// user account.
96///
97// TODO: Introduce RoomMember and track by occupant-id
98#[derive(Clone, Debug)]
99pub struct RoomNick(ResourcePart);
100
101impl RoomNick {
102 pub fn new(nick: ResourcePart) -> Self {
103 Self(nick)
104 }
105
106 pub fn from_resource_ref(nick: &ResourceRef) -> Self {
107 Self(nick.to_owned())
108 }
109}
110
111impl AsRef<ResourceRef> for RoomNick {
112 fn as_ref(&self) -> &ResourceRef {
113 self.0.as_ref()
114 }
115}
116
117impl From<RoomNick> for ResourcePart {
118 fn from(room_nick: RoomNick) -> Self {
119 room_nick.0
120 }
121}
122
123impl fmt::Display for RoomNick {
124 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
125 write!(f, "{}", self.0)
126 }
127}
128
129impl core::str::FromStr for RoomNick {
130 type Err = crate::jid::Error;
131
132 fn from_str(s: &str) -> Result<Self, Self::Err> {
133 Ok(Self::new(ResourcePart::new(s)?.into()))
134 }
135}
136
137impl core::ops::Deref for RoomNick {
138 type Target = ResourcePart;
139
140 fn deref(&self) -> &ResourcePart {
141 &self.0
142 }
143}
144
145#[cfg(test)]
146mod tests {
147 #[test]
148 fn reexports() {
149 #[allow(unused_imports)]
150 use crate::jid;
151 #[allow(unused_imports)]
152 use crate::minidom;
153 #[allow(unused_imports)]
154 use crate::parsers;
155 #[allow(unused_imports)]
156 use crate::tokio_xmpp;
157 }
158}
159
160// The test below is dysfunctional since we have moved to StanzaStream. The
161// StanzaStream will attempt to connect to foo@bar indefinitely.
162// Keeping it here as inspiration for future integration tests.
163/*
164#[cfg(all(test, any(feature = "starttls-rust", feature = "starttls-native")))]
165mod tests {
166 use super::jid::{BareJid, ResourcePart};
167 use super::{ClientBuilder, ClientFeature, ClientType, Event};
168 use std::str::FromStr;
169 use tokio_xmpp::Client as TokioXmppClient;
170
171 #[tokio::test]
172 async fn test_simple() {
173 let jid = BareJid::from_str("foo@bar").unwrap();
174 let nick = RoomNick::from_str("bot").unwrap();
175
176 let client = TokioXmppClient::new(jid.clone(), "meh");
177
178 // Client instance
179 let client_builder = ClientBuilder::new(jid, "meh")
180 .set_client(ClientType::Bot, "xmpp-rs")
181 .set_website("https://xmpp.rs")
182 .set_default_nick(nick)
183 .enable_feature(ClientFeature::ContactList);
184
185 #[cfg(feature = "avatars")]
186 let client_builder = client_builder.enable_feature(ClientFeature::Avatars);
187
188 let mut agent = client_builder.build_impl(client);
189
190 loop {
191 let events = agent.wait_for_events().await;
192 assert!(match events[0] {
193 Event::Disconnected(_) => true,
194 _ => false,
195 });
196 assert_eq!(events.len(), 1);
197 break;
198 }
199 }
200}
201*/