async_circe/

lib.rs

//! A simple IRC crate written in rust
//! ```run_fut
//! use async_circe::{commands::Command, Client, Config};
//!
//! #[tokio::main(flavor = "current_thread")]
//! async fn main() -> Result<(), tokio::io::Error> {
//!     let config = Config::default();
//!     let mut client = Client::new(config).await.unwrap();
//!     client.identify().await.unwrap();
//!
//!     loop {
//!         if let Some(command) = client.read().await? {
//!             if let Command::PRIVMSG(nick, channel, message) = command {
//!                 println!("{} in {}: {}", nick, channel, message);
//!             }
//!         }
//!     }
//! }
//! ```
//!
//! The crate requires `tokio` with the `macros` and `rt` feature enabled to function.<br>
//! For more examples (connecting to IRCs that dont use SSL, getting the config from
//! a toml file, debugging or just in general an overview how a project with async-circe
//! is structured) see the [examples](https://git.karx.xyz/circe/async-circe/src/branch/master/examples) folder on our git.

#![warn(missing_docs)] // We want everything documented
#![allow(clippy::needless_return)] // Wants to remove a return statement, but when it's removed the code doesn't compile
#![feature(doc_cfg)]

use tokio::io::BufReader;
use tokio::io::Error;
use tokio::io::{AsyncBufReadExt, AsyncWriteExt};
use tokio::net::TcpStream;

#[cfg(feature = "tls")]
use native_tls::TlsConnector;

#[cfg(feature = "toml_config")]
use serde_derive::Deserialize;
#[cfg(feature = "toml_config")]
use std::fs::File;
#[cfg(feature = "toml_config")]
use std::io::Read;
#[cfg(any(doc, feature = "toml_config"))]
use std::path::Path;
#[cfg(feature = "toml_config")]
use tokio::io::ErrorKind;

pub mod commands;

/// An IRC client
pub struct Client {
    config: Config,
    #[cfg(not(feature = "tls"))]
    buf_reader: BufReader<TcpStream>,
    #[cfg(feature = "tls")]
    buf_reader: BufReader<tokio_native_tls::TlsStream<tokio::net::TcpStream>>,
}

/// Config for the IRC client<br>
/// For more information about what arguments the IRC commands take, see [`commands::Command`].
#[derive(Clone, Debug, Default)]
#[cfg_attr(feature = "toml_config", derive(Deserialize))]
pub struct Config {
    channels: Vec<String>,
    host: String,
    mode: Option<String>,
    nickname: Option<String>,
    port: u16,
    username: String,
}

impl Client {
    /// Creates a new client with a given [`Config`].
    /// # Example
    /// ```run_fut
    /// # let config = Default::default();
    /// let mut client = Client::new(config).await?;
    /// # Ok(())
    /// ```
    /// # Errors
    /// Returns error if the client could not connect to the host.
    /// # Panics
    /// Panics if the client can't connect to the given host.
    pub async fn new(config: Config) -> Result<Self, Error> {
        tracing::debug!("Creating TcpStream");
        let stream = TcpStream::connect(format!("{}:{}", config.host, config.port))
            .await
            .unwrap();
        tracing::debug!("New TcpStream created");

        #[cfg(feature = "tls")]
        {
            let connector = TlsConnector::builder().build().unwrap();
            let async_connector = tokio_native_tls::TlsConnector::from(connector);

            let sslstream = async_connector
                .connect(config.host.as_str(), stream)
                .await
                .unwrap();

            let buf_reader = BufReader::new(sslstream);

            return Ok(Self { config, buf_reader });
        };

        #[cfg(not(feature = "tls"))]
        {
            let buf_reader = BufReader::new(stream);
            return Ok(Self { config, buf_reader });
        };
    }

    /// Identify user and joins the in the [`Config`] specified channels.
    /// # Example
    /// ```run_fut
    /// # let config = Default::default();
    /// # let mut client = Client::new(config).await?;
    /// client.identify().await?;
    /// # Ok(())
    /// ```
    /// # Errors
    /// Returns error if the client could not write to the stream.
    pub async fn identify(&mut self) -> Result<(), Error> {
        self.cap_mode(commands::CapMode::LS).await?;
        self.cap_mode(commands::CapMode::END).await?;

        self.user(
            self.config.username.clone(),
            "*",
            "*",
            self.config.username.clone(),
        )
        .await?;

        if let Some(nick) = self.config.nickname.clone() {
            self.nick(&nick).await?;
        } else {
            self.nick(&self.config.username.clone()).await?;
        }

        loop {
            if let Some(command) = self.read().await? {
                match command {
                    commands::Command::PING(code) => {
                        self.pong(&code).await?;
                    }
                    commands::Command::OTHER(line) => {
                        tracing::trace!("{}", line);
                        if line.contains("001") {
                            break;
                        }
                    }
                    _ => {}
                }
            }
        }

        let config = self.config.clone();
        let user = {
            if let Some(nick) = config.nickname {
                nick
            } else {
                config.username
            }
        };

        if let Some(mode) = config.mode {
            self.mode(&user, Some(&mode)).await?;
        }

        for channel in &config.channels {
            self.join(channel).await?;
        }

        tracing::info!("async-circe has identified");
        Ok(())
    }

    async fn read_string(&mut self) -> Result<Option<String>, tokio::io::Error> {
        let mut buffer = String::new();

        let num_bytes = match self.buf_reader.read_line(&mut buffer).await {
            Ok(b) => b,
            Err(e) => {
                tracing::error!("{}", e);
                return Err(e);
            }
        };

        if num_bytes == 0 {
            return Ok(None);
        }

        Ok(Some(buffer))
    }

    /// Read data coming from the IRC as a [`commands::Command`].
    /// # Example
    /// ```run_fut
    /// # use async_circe::*;
    /// # let config = Default::default();
    /// # let mut client = Client::new(config).await?;
    /// # client.identify().await?;
    /// loop {
    ///    if let Some(ref command) = client.read().await? {
    ///        if let commands::Command::PRIVMSG(nick, channel, message) = command {
    ///            println!("{} in {}: {}", nick, channel, message);
    ///        }
    ///    }
    /// # break;
    /// }
    /// # Ok(())
    /// ```
    /// # Errors
    /// Returns IO errors from the TcpStream.
    pub async fn read(&mut self) -> Result<Option<commands::Command>, tokio::io::Error> {
        if let Some(string) = self.read_string().await? {
            let command = commands::Command::command_from_str(&string).await;

            if let commands::Command::PING(command) = command {
                if let Err(_e) = self.pong(&command).await {
                    return Ok(None);
                }
                return Ok(Some(commands::Command::PONG("".to_string())));
            }

            return Ok(Some(command));
        }

        Ok(None)
    }

    async fn write(&mut self, data: String) -> Result<(), Error> {
        tracing::trace!("{:?}", data);
        self.buf_reader.write_all(data.as_bytes()).await?;

        Ok(())
    }

    /// Request information about the admin of a given server.
    /// # Example
    /// ```run_fut
    /// # use async_circe::*;
    /// # let config = Default::default();
    /// # let mut client = Client::new(config).await?;
    /// # client.identify().await?;
    /// client.admin("libera.chat").await?;
    /// # Ok(())
    /// ```
    /// # Errors
    /// Returns IO errors from the TcpStream.
    pub async fn admin(&mut self, target: &str) -> Result<(), Error> {
        self.write(format!("ADMIN {}\r\n", target)).await?;
        Ok(())
    }

    /// Set the status of the client.
    /// # Example
    /// ```run_fut
    /// # let config = Default::default();
    /// # let mut client = Client::new(config).await?;
    /// # client.identify().await?;
    /// client.away("afk").await?;
    /// # Ok(())
    /// ```
    /// # Errors
    /// Returns IO errors from the TcpStream.
    pub async fn away(&mut self, message: &str) -> Result<(), Error> {
        self.write(format!("AWAY {}\r\n", message)).await?;
        Ok(())
    }

    #[doc(hidden)]
    pub async fn cap_mode(&mut self, mode: commands::CapMode) -> Result<(), Error> {
        let cap_mode = match mode {
            commands::CapMode::LS => "CAP LS 302\r\n",
            commands::CapMode::END => "CAP END\r\n",
        };
        self.write(cap_mode.to_string()).await?;
        Ok(())
    }

    /// Invite someone to a channel.
    /// # Example
    /// ```run_fut
    /// # let config = Default::default();
    /// # let mut client = Client::new(config).await?;
    /// # client.identify().await?;
    /// client.invite("liblemonirc", "#async-circe").await?;
    /// # Ok(())
    /// ```
    /// # Errors
    /// Returns IO errors from the TcpStream.
    pub async fn invite(&mut self, username: &str, channel: &str) -> Result<(), Error> {
        self.write(format!("INVITE {} {}\r\n", username, channel))
            .await?;
        Ok(())
    }

    /// Join a channel.
    /// # Example
    /// ```run_fut
    /// # let config = Default::default();
    /// # let mut client = Client::new(config).await?;
    /// # client.identify().await?;
    /// client.join("#chaos").await?;
    /// # Ok(())
    /// ```
    /// # Errors
    /// Returns IO errors from the TcpStream.
    pub async fn join(&mut self, channel: &str) -> Result<(), Error> {
        self.write(format!("JOIN {}\r\n", channel)).await?;
        Ok(())
    }

    /// List available channels on an IRC, or users in a channel.
    /// # Example
    /// ```run_fut
    /// # let config = Default::default();
    /// # let mut client = Client::new(config).await?;
    /// # client.identify().await?;
    /// client.list(None, None).await?;
    /// # Ok(())
    /// ```
    /// # Errors
    /// Returns IO errors from the TcpStream.
    pub async fn list(&mut self, channel: Option<&str>, server: Option<&str>) -> Result<(), Error> {
        let mut formatted = "LIST".to_string();
        if let Some(channel) = channel {
            formatted.push_str(format!(" {}", channel).as_str());
        }
        if let Some(server) = server {
            formatted.push_str(format!(" {}", server).as_str());
        }
        formatted.push_str("\r\n");
        self.write(formatted).await?;
        Ok(())
    }

    /// Set the mode for a user.
    /// # Example
    /// ```run_fut
    /// # let config = Default::default();
    /// # let mut client = Client::new(config).await?;
    /// # client.identify().await?;
    /// client.mode("test", Some("+B")).await?;
    /// # Ok(())
    /// ```
    /// # Errors
    /// Returns IO errors from the TcpStream.
    pub async fn mode(&mut self, target: &str, mode: Option<&str>) -> Result<(), Error> {
        if let Some(mode) = mode {
            self.write(format!("MODE {} {}\r\n", target, mode,)).await?;
        } else {
            self.write(format!("MODE {}\r\n", target)).await?;
        }
        Ok(())
    }

    /// Get all the people online in channels.
    /// # Example
    /// ```run_fut
    /// # let config = Default::default();
    /// # let mut client = Client::new(config).await?;
    /// # client.identify().await?;
    /// client.names("#chaos,#async-circe", None).await?;
    /// # Ok(())
    /// ```
    /// # Errors
    /// Returns IO errors from the TcpStream.
    pub async fn names(&mut self, channel: &str, server: Option<&str>) -> Result<(), Error> {
        if let Some(server) = server {
            self.write(format!("NAMES {} {}\r\n", channel, server))
                .await?;
        } else {
            self.write(format!("NAMES {}\r\n", channel)).await?;
        }
        Ok(())
    }

    /// Change your nickname on a server.
    /// # Example
    /// ```run_fut
    /// # let config = Default::default();
    /// # let mut client = Client::new(config).await?;
    /// # client.identify().await?;
    /// client.nick("Not async-circe").await?;
    /// # Ok(())
    /// ```
    /// # Errors
    /// Returns IO errors from the TcpStream.
    pub async fn nick(&mut self, nickname: &str) -> Result<(), Error> {
        self.write(format!("NICK {}\r\n", nickname)).await?;
        Ok(())
    }

    /// Authentificate as an operator on a server.
    /// # Example
    /// ```run_fut
    /// # let config = Default::default();
    /// # let mut client = Client::new(config).await?;
    /// # client.identify().await?;
    /// client.oper("username", "password").await?;
    /// # Ok(())
    /// ```
    /// # Errors
    /// Returns IO errors from the TcpStream.
    pub async fn oper(&mut self, username: &str, password: &str) -> Result<(), Error> {
        self.write(format!("OPER {} {}\r\n", username, password))
            .await?;
        Ok(())
    }

    /// Leave a channel.
    /// # Example
    /// ```run_fut
    /// # let config = Default::default();
    /// # let mut client = Client::new(config).await?;
    /// # client.identify().await?;
    /// client.part("#chaos").await?;
    /// # Ok(())
    /// ```
    /// # Errors
    /// Returns IO errors from the TcpStream.
    pub async fn part(&mut self, channel: &str) -> Result<(), Error> {
        self.write(format!("PART {}\r\n", channel)).await?;
        Ok(())
    }

    #[doc(hidden)]
    pub async fn pass(&mut self, password: &str) -> Result<(), Error> {
        self.write(format!("PASS {}\r\n", password)).await?;
        Ok(())
    }

    /// Tests the presence of a connection to a server.
    /// # Example
    /// ```run_fut
    /// # let config = Default::default();
    /// # let mut client = Client::new(config).await?;
    /// # client.identify().await?;
    /// client.ping("libera.chat", None).await?;
    /// # Ok(())
    /// ```
    /// # Errors
    /// Returns IO errors from the TcpStream.
    pub async fn ping(&mut self, server1: &str, server2: Option<&str>) -> Result<(), Error> {
        if let Some(server2) = server2 {
            self.write(format!("PING {} {}\r\n", server1, server2))
                .await?;
        } else {
            self.write(format!("PING {}\r\n", server1)).await?;
        }
        // TODO look if we actually get a PONG back
        Ok(())
    }

    #[doc(hidden)]
    pub async fn pong(&mut self, ping: &str) -> Result<(), Error> {
        self.write(format!("PONG {}\r\n", ping)).await?;
        Ok(())
    }

    /// Send a message to a channel.
    /// # Example
    /// ```run_fut
    /// # let config = Default::default();
    /// # let mut client = Client::new(config).await?;
    /// # client.identify().await?;
    /// client.privmsg("#chaos", "Hello").await?;
    /// # Ok(())
    /// ```
    /// # Errors
    /// Returns IO errors from the TcpStream.
    pub async fn privmsg(&mut self, channel: &str, message: &str) -> Result<(), Error> {
        self.write(format!("PRIVMSG {} {}\r\n", channel, message))
            .await?;
        Ok(())
    }

    /// Leave the IRC server you are connected to.
    /// # Example
    /// ```run_fut
    /// # use async_circe::*;
    /// # let config = Default::default();
    /// # let mut client = Client::new(config).await?;
    /// # client.identify().await?;
    /// client.quit(None).await?;
    /// # Ok(())
    /// ```
    /// # Errors
    /// Returns IO errors from the TcpStream.
    pub async fn quit(&mut self, message: Option<&str>) -> Result<(), Error> {
        if let Some(message) = message {
            self.write(format!("QUIT :{}\r\n", message)).await?;
        } else {
            self.write(format!(
                "QUIT :async-circe {} (https://crates.io/crates/async-circe)\r\n",
                env!("CARGO_PKG_VERSION")
            ))
            .await?;
        }
        tracing::info!("async-circe shutting down");
        self.buf_reader.shutdown().await?;
        Ok(())
    }

    /// Get the topic of a channel.
    /// # Example
    /// ```run_fut
    /// # use async_circe::*;
    /// # let config = Default::default();
    /// # let mut client = Client::new(config).await?;
    /// # client.identify().await?;
    /// client.topic("#chaos", None).await?;
    /// # Ok(())
    /// ```
    /// Set the topic of a channel.
    /// # Example
    /// ```run_fut
    /// # let config = Default::default();
    /// # let mut client = Client::new(config).await?;
    /// # client.identify().await?;
    /// client.topic("#chaos", Some("CHAOS")).await?;
    /// # Ok(())
    /// ```
    /// # Errors
    /// Returns IO errors from the TcpStream.
    pub async fn topic(&mut self, channel: &str, topic: Option<&str>) -> Result<(), Error> {
        if let Some(topic) = topic {
            self.write(format!("TOPIC {} :{}\r\n", channel, topic))
                .await?;
        } else {
            self.write(format!("TOPIC {}\r\n", channel)).await?;
        }
        Ok(())
    }

    #[doc(hidden)]
    pub async fn user(
        &mut self,
        username: String,
        s1: &str,
        s2: &str,
        realname: String,
    ) -> Result<(), Error> {
        self.write(format!("USER {} {} {} :{}\r\n", username, s1, s2, realname))
            .await?;
        Ok(())
    }
}

impl Config {
    /// Create a new config for the client
    /// # Example
    /// ```rust
    /// # use async_circe::Config;
    /// let config = Config::new(
    ///     &["#chaos", "#async-circe"],
    ///     "karx.xyz",
    ///     Some("+B"),
    ///     Some("async-circe"),
    ///     6697,
    ///     "circe",
    /// );
    /// ```
    #[must_use]
    pub fn new(
        channels: &[&'static str],
        host: &str,
        mode: Option<&'static str>,
        nickname: Option<&'static str>,
        port: u16,
        username: &str,
    ) -> Self {
        tracing::info!("New async-circe client config");
        // Conversion from &'static str to String
        let channels_config = channels
            .iter()
            .map(|channel| (*channel).to_string())
            .collect();

        let mode_config: Option<String>;
        if let Some(mode) = mode {
            mode_config = Some(mode.to_string());
        } else {
            mode_config = None;
        }

        let nickname_config: Option<String>;
        if let Some(nickname) = nickname {
            nickname_config = Some(nickname.to_string());
        } else {
            nickname_config = Some(username.to_string());
        }

        let config = Self {
            channels: channels_config,
            host: host.into(),
            mode: mode_config,
            nickname: nickname_config,
            port,
            username: username.into(),
        };

        tracing::debug!("async-circe config: {:?}", config);
        config
    }

    /// Allows for configuring async-circe at runtime.
    /// # Example
    /// ```run_fut
    /// # use async_circe::Config;
    /// let config = Config::runtime_config(
    ///     vec!["#chaos".to_string(), "#async-circe".to_string()],
    ///     "karx.xyz".to_string(),
    ///     Some("+B".to_string()),
    ///     Some("async-circe".to_string()),
    ///     6697,
    ///     "circe".to_string(),
    /// );
    /// ```
    #[must_use]
    pub fn runtime_config(
        channels: Vec<String>,
        host: String,
        mode: Option<String>,
        nickname: Option<String>,
        port: u16,
        username: String,
    ) -> Self {
        tracing::info!("New async-circe client config");
        let mode_config: Option<String>;
        if let Some(mode) = mode {
            mode_config = Some(mode);
        } else {
            mode_config = None;
        }

        let nickname_config: Option<String>;
        if let Some(nickname) = nickname {
            nickname_config = Some(nickname);
        } else {
            nickname_config = Some(username.to_string());
        }

        let config = Self {
            channels,
            host,
            mode: mode_config,
            nickname: nickname_config,
            port,
            username,
        };

        tracing::debug!("async-circe config: {:?}", config);
        config
    }

    /// Create a config from a toml file
    /// # Example
    /// ```toml
    /// #Config.toml
    /// channels = ["#chaos", "#async-circe"]
    /// host = "karx.xyz"
    /// mode = "+B"
    /// nickname = "async-circe"
    /// port = 6667
    /// username = "circe"
    /// ```
    /// ```run_fut
    /// let config = Config::from_toml("Config.toml")?;
    /// ```
    /// # Errors
    /// Returns an Error if the file cannot be opened or if the TOML is invalid
    #[cfg(any(doc, feature = "toml_config"))]
    #[doc(cfg(feature = "toml_config"))]
    pub fn from_toml<P: AsRef<Path>>(path: P) -> Result<Self, Error> {
        tracing::info!("New async-circe client config");
        let mut file = File::open(&path)?;
        let mut data = String::new();
        file.read_to_string(&mut data)?;

        let config = toml::from_str(&data)
            .map_err(|e| Error::new(ErrorKind::Other, format!("Invalid TOML: {}", e)));
        tracing::debug!("async-circe config: {:?}", config);
        config
    }
}