From b929a3c71eca8bf1e3208bf042a502b34c3a4a1a Mon Sep 17 00:00:00 2001 From: Astro Date: Thu, 2 Aug 2018 19:58:19 +0200 Subject: [PATCH] doc --- src/client/mod.rs | 6 ++++++ src/component/mod.rs | 9 +++++++++ src/event.rs | 8 ++++++++ src/lib.rs | 4 ++++ src/starttls.rs | 3 ++- src/xmpp_codec.rs | 15 +++++++++++++-- src/xmpp_stream.rs | 15 +++++++++++++++ 7 files changed, 57 insertions(+), 3 deletions(-) diff --git a/src/client/mod.rs b/src/client/mod.rs index dc948fa..95b9242 100644 --- a/src/client/mod.rs +++ b/src/client/mod.rs @@ -22,7 +22,9 @@ use self::auth::ClientAuth; mod bind; use self::bind::ClientBind; +/// XMPP client connection and state pub struct Client { + /// The client's current Jabber-Id pub jid: Jid, state: ClientState, } @@ -38,6 +40,10 @@ enum ClientState { } impl Client { + /// Start a new XMPP client + /// + /// Start polling the returned instance so that it will connect + /// and yield events. pub fn new(jid: &str, password: &str, handle: Handle) -> Result { let jid = try!(Jid::from_str(jid)); let password = password.to_owned(); diff --git a/src/component/mod.rs b/src/component/mod.rs index 04613c5..21ef897 100644 --- a/src/component/mod.rs +++ b/src/component/mod.rs @@ -1,3 +1,6 @@ +//! Components in XMPP are services/gateways that are logged into an +//! XMPP server under a JID consisting of just a domain name. They are +//! allowed to use any user and resource identifiers in their stanzas. use std::mem::replace; use std::str::FromStr; use std::error::Error; @@ -16,7 +19,9 @@ use super::event::Event; mod auth; use self::auth::ComponentAuth; +/// Component connection to an XMPP server pub struct Component { + /// The component's Jabber-Id pub jid: Jid, state: ComponentState, } @@ -32,6 +37,10 @@ enum ComponentState { } impl Component { + /// Start a new XMPP component + /// + /// Start polling the returned instance so that it will connect + /// and yield events. pub fn new(jid: &str, password: &str, server: &str, port: u16, handle: Handle) -> Result { let jid = try!(Jid::from_str(jid)); let password = password.to_owned(); diff --git a/src/event.rs b/src/event.rs index 8ff44bd..7a225ba 100644 --- a/src/event.rs +++ b/src/event.rs @@ -1,13 +1,18 @@ use minidom::Element; +/// High-level event on the Stream implemented by Client and Component #[derive(Debug)] pub enum Event { + /// Stream is connected and initialized Online, + /// Stream end Disconnected, + /// Received stanza/nonza Stanza(Element), } impl Event { + /// `Online` event? pub fn is_online(&self) -> bool { match *self { Event::Online => true, @@ -15,6 +20,7 @@ impl Event { } } + /// `Stanza` event? pub fn is_stanza(&self, name: &str) -> bool { match *self { Event::Stanza(ref stanza) => stanza.name() == name, @@ -22,6 +28,7 @@ impl Event { } } + /// If this is a `Stanza` event, get its data pub fn as_stanza(&self) -> Option<&Element> { match *self { Event::Stanza(ref stanza) => Some(stanza), @@ -29,6 +36,7 @@ impl Event { } } + /// If this is a `Stanza` event, unwrap into its data pub fn into_stanza(self) -> Option { match self { Event::Stanza(stanza) => Some(stanza), diff --git a/src/lib.rs b/src/lib.rs index 40da556..ebba1f1 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,3 +1,7 @@ +#![deny(unsafe_code, unused, missing_docs)] + +//! XMPP implemeentation with asynchronous I/O using Tokio. + extern crate futures; extern crate tokio_core; extern crate tokio_io; diff --git a/src/starttls.rs b/src/starttls.rs index 7338b55..6ac23ac 100644 --- a/src/starttls.rs +++ b/src/starttls.rs @@ -11,10 +11,11 @@ use jid::Jid; use xmpp_codec::Packet; use xmpp_stream::XMPPStream; - +/// XMPP TLS XML namespace pub const NS_XMPP_TLS: &str = "urn:ietf:params:xml:ns:xmpp-tls"; +/// XMPP stream that switches to TLS if available in received features pub struct StartTlsClient { state: StartTlsClientState, jid: Jid, diff --git a/src/xmpp_codec.rs b/src/xmpp_codec.rs index f38d845..ededf21 100644 --- a/src/xmpp_codec.rs +++ b/src/xmpp_codec.rs @@ -1,3 +1,5 @@ +//! XML stream parser for XMPP + use std; use std::default::Default; use std::iter::FromIterator; @@ -15,17 +17,22 @@ use xml5ever::interface::Attribute; use bytes::{BytesMut, BufMut}; use quick_xml::Writer as EventWriter; -// const NS_XMLNS: &'static str = "http://www.w3.org/2000/xmlns/"; - +/// Anything that can be sent or received on an XMPP/XML stream #[derive(Debug)] pub enum Packet { + /// General error (`InvalidInput`) Error(Box), + /// `` start tag StreamStart(HashMap), + /// A complete stanza or nonza Stanza(Element), + /// Plain text (think whitespace keep-alive) Text(String), + /// `` closing tag StreamEnd, } +/// Parser state struct ParserSink { // Ready stanzas, shared with XMPPCodec queue: Rc>>, @@ -47,6 +54,7 @@ impl ParserSink { self.queue.borrow_mut().push_back(pkt); } + /// Lookup XML namespace declaration for given prefix (or no prefix) fn lookup_ns(&self, prefix: &Option) -> Option<&str> { for nss in self.ns_stack.iter().rev() { if let Some(ns) = nss.get(prefix) { @@ -166,6 +174,7 @@ impl TokenSink for ParserSink { // } } +/// Stateful encoder/decoder for a bytestream from/to XMPP `Packet` pub struct XMPPCodec { /// Outgoing ns: Option, @@ -179,6 +188,7 @@ pub struct XMPPCodec { } impl XMPPCodec { + /// Constructor pub fn new() -> Self { let queue = Rc::new(RefCell::new(VecDeque::new())); let sink = ParserSink::new(queue.clone()); @@ -300,6 +310,7 @@ impl Encoder for XMPPCodec { } } +/// Write XML-escaped text string pub fn write_text(text: &str, writer: &mut W) -> Result<(), std::fmt::Error> { write!(writer, "{}", escape(text)) } diff --git a/src/xmpp_stream.rs b/src/xmpp_stream.rs index e5ba9fc..c5443a9 100644 --- a/src/xmpp_stream.rs +++ b/src/xmpp_stream.rs @@ -1,3 +1,5 @@ +//! `XMPPStream` is the common container for all XMPP network connections + use futures::{Poll, Stream, Sink, StartSend}; use futures::sink::Send; use tokio_io::{AsyncRead, AsyncWrite}; @@ -8,16 +10,26 @@ use jid::Jid; use xmpp_codec::{XMPPCodec, Packet}; use stream_start::StreamStart; +/// namespace pub const NS_XMPP_STREAM: &str = "http://etherx.jabber.org/streams"; +/// Wraps a `stream` pub struct XMPPStream { + /// The local Jabber-Id pub jid: Jid, + /// Codec instance pub stream: Framed, + /// `` for XMPP version 1.0 pub stream_features: Element, + /// Root namespace + /// + /// This is different for either c2s, s2s, or component + /// connections. pub ns: String, } impl XMPPStream { + /// Constructor pub fn new(jid: Jid, stream: Framed, ns: String, @@ -25,15 +37,18 @@ impl XMPPStream { XMPPStream { jid, stream, stream_features, ns } } + /// Send a `` start tag pub fn start(stream: S, jid: Jid, ns: String) -> StreamStart { let xmpp_stream = Framed::new(stream, XMPPCodec::new()); StreamStart::from_stream(xmpp_stream, jid, ns) } + /// Unwraps the inner stream pub fn into_inner(self) -> S { self.stream.into_inner() } + /// Re-run `start()` pub fn restart(self) -> StreamStart { Self::start(self.stream.into_inner(), self.jid, self.ns) }