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
7use std::io;
8
9use xmpp_parsers::{jid::Jid, stream_features::StreamFeatures};
10
11use crate::{
12 connect::ServerConnector,
13 error::Error,
14 stanzastream::{StanzaStage, StanzaState, StanzaStream, StanzaToken},
15 xmlstream::Timeouts,
16 Stanza,
17};
18
19#[cfg(feature = "direct-tls")]
20use crate::connect::DirectTlsServerConnector;
21#[cfg(any(feature = "direct-tls", feature = "starttls", feature = "insecure-tcp"))]
22use crate::connect::DnsConfig;
23#[cfg(feature = "starttls")]
24use crate::connect::StartTlsServerConnector;
25#[cfg(feature = "insecure-tcp")]
26use crate::connect::TcpServerConnector;
27
28mod iq;
29pub(crate) mod login;
30mod stream;
31
32pub use iq::{IqFailure, IqRequest, IqResponse, IqResponseToken};
33
34/// XMPP client connection and state
35///
36/// This implements the `futures` crate's [`Stream`](#impl-Stream) to receive
37/// stream state changes as well as stanzas received via the stream.
38///
39/// To send stanzas, the [`send_stanza`][`Client::send_stanza`] method can be
40/// used.
41#[derive(Debug)]
42pub struct Client {
43 stream: StanzaStream,
44 bound_jid: Option<Jid>,
45 features: Option<StreamFeatures>,
46 iq_response_tracker: iq::IqResponseTracker,
47}
48
49impl Client {
50 /// Get the client's bound JID (the one reported by the XMPP
51 /// server).
52 pub fn bound_jid(&self) -> Option<&Jid> {
53 self.bound_jid.as_ref()
54 }
55
56 /// Send a stanza.
57 ///
58 /// This will automatically allocate an ID if the stanza has no ID set.
59 /// The returned `StanzaToken` is awaited up to the [`StanzaStage::Sent`]
60 /// stage, which means that this coroutine only returns once the stanza
61 /// has actually been written to the XMPP transport.
62 ///
63 /// Note that this does not imply that it has been *reeceived* by the
64 /// peer, nor that it has been successfully processed. To confirm that a
65 /// stanza has been received by a peer, the [`StanzaToken::wait_for`]
66 /// method can be called with [`StanzaStage::Acked`], but that stage will
67 /// only ever be reached if the server supports XEP-0198 and it has been
68 /// negotiated successfully (this may change in the future).
69 ///
70 /// For sending Iq request stanzas, it is recommended to use
71 /// [`send_iq`][`Self::send_iq`], which allows awaiting the response.
72 pub async fn send_stanza(&mut self, mut stanza: Stanza) -> Result<StanzaToken, io::Error> {
73 stanza.ensure_id();
74 let mut token = self.stream.send(Box::new(stanza)).await;
75 match token.wait_for(StanzaStage::Sent).await {
76 // Queued < Sent, so it cannot be reached.
77 Some(StanzaState::Queued) => unreachable!(),
78
79 None | Some(StanzaState::Dropped) => Err(io::Error::new(
80 io::ErrorKind::NotConnected,
81 "stream disconnected fatally before stanza could be sent",
82 )),
83 Some(StanzaState::Failed { error }) => Err(error.into_io_error()),
84 Some(StanzaState::Sent { .. }) | Some(StanzaState::Acked { .. }) => Ok(token),
85 }
86 }
87
88 /// Send an IQ request and return a token to retrieve the response.
89 ///
90 /// This coroutine method will complete once the Iq has been sent to the
91 /// server. The returned `IqResponseToken` can be used to await the
92 /// response. See also the documentation of [`IqResponseToken`] for more
93 /// information on the behaviour of these tokens.
94 ///
95 /// **Important**: Even though IQ responses are delivered through the
96 /// returned token (and never through the `Stream`), the
97 /// [`Stream`][`futures::Stream`]
98 /// implementation of the [`Client`] **must be polled** to make progress
99 /// on the stream and to process incoming stanzas and thus to deliver them
100 /// to the returned token.
101 ///
102 /// **Note**: If an IQ response arrives after the `token` has been
103 /// dropped (e.g. due to a timeout), it will be delivered through the
104 /// `Stream` like any other stanza.
105 pub async fn send_iq(&mut self, to: Option<Jid>, req: IqRequest) -> IqResponseToken {
106 let (iq, mut token) = self.iq_response_tracker.allocate_iq_handle(
107 // from is always None for a client
108 None, to, req,
109 );
110 let stanza_token = self.stream.send(Box::new(iq.into())).await;
111 token.set_stanza_token(stanza_token);
112 token
113 }
114
115 /// Get the stream features (`<stream:features/>`) of the underlying
116 /// stream.
117 ///
118 /// If the stream has not completed negotiation yet, this will return
119 /// `None`. Note that stream features may change at any point due to a
120 /// transparent reconnect.
121 pub fn get_stream_features(&self) -> Option<&StreamFeatures> {
122 self.features.as_ref()
123 }
124
125 /// Close the client cleanly.
126 ///
127 /// This performs an orderly stream shutdown, ensuring that all resources
128 /// are correctly cleaned up.
129 pub async fn send_end(self) -> Result<(), Error> {
130 self.stream.close().await;
131 Ok(())
132 }
133}
134
135#[cfg(feature = "direct-tls")]
136impl Client {
137 /// Start a new XMPP client using DirectTLS transport and autoreconnect
138 ///
139 /// It use RFC 7590 _xmpps-client._tcp lookup for connector details.
140 pub fn new_direct_tls<J: Into<Jid>, P: Into<String>>(jid: J, password: P) -> Self {
141 let jid_ref = jid.into();
142 let dns_config = DnsConfig::srv_xmpps(jid_ref.domain().as_ref());
143 Self::new_with_connector(
144 jid_ref,
145 password,
146 DirectTlsServerConnector::from(dns_config),
147 Timeouts::default(),
148 )
149 }
150
151 /// Start a new XMPP client with direct TLS transport, useful for testing or
152 /// when one does not want to rely on dns lookups
153 pub fn new_direct_tls_with_config<J: Into<Jid>, P: Into<String>>(
154 jid: J,
155 password: P,
156 dns_config: DnsConfig,
157 timeouts: Timeouts,
158 ) -> Self {
159 Self::new_with_connector(
160 jid,
161 password,
162 DirectTlsServerConnector::from(dns_config),
163 timeouts,
164 )
165 }
166}
167
168#[cfg(feature = "starttls")]
169impl Client {
170 /// Start a new XMPP client using StartTLS transport and autoreconnect
171 ///
172 /// Start polling the returned instance so that it will connect
173 /// and yield events.
174 pub fn new<J: Into<Jid>, P: Into<String>>(jid: J, password: P) -> Self {
175 let jid = jid.into();
176 let dns_config = DnsConfig::srv_default_client(jid.domain().as_ref());
177 Self::new_starttls(jid, password, dns_config, Timeouts::default())
178 }
179
180 /// Start a new XMPP client with StartTLS transport and specific DNS config
181 pub fn new_starttls<J: Into<Jid>, P: Into<String>>(
182 jid: J,
183 password: P,
184 dns_config: DnsConfig,
185 timeouts: Timeouts,
186 ) -> Self {
187 Self::new_with_connector(
188 jid,
189 password,
190 StartTlsServerConnector::from(dns_config),
191 timeouts,
192 )
193 }
194}
195
196#[cfg(feature = "insecure-tcp")]
197impl Client {
198 /// Start a new XMPP client with plaintext insecure connection and specific DNS config
199 pub fn new_plaintext<J: Into<Jid>, P: Into<String>>(
200 jid: J,
201 password: P,
202 dns_config: DnsConfig,
203 timeouts: Timeouts,
204 ) -> Self {
205 Self::new_with_connector(
206 jid,
207 password,
208 TcpServerConnector::from(dns_config),
209 timeouts,
210 )
211 }
212}
213
214impl Client {
215 /// Start a new client given that the JID is already parsed.
216 pub fn new_with_connector<J: Into<Jid>, P: Into<String>, C: ServerConnector>(
217 jid: J,
218 password: P,
219 connector: C,
220 timeouts: Timeouts,
221 ) -> Self {
222 Self {
223 stream: StanzaStream::new_c2s(connector, jid.into(), password.into(), timeouts, 16),
224 bound_jid: None,
225 features: None,
226 iq_response_tracker: iq::IqResponseTracker::new(),
227 }
228 }
229}