From 917ecbc4772c70aa06623bd0116e74e3eae33582 Mon Sep 17 00:00:00 2001 From: Alexis Mousset Date: Mon, 30 Apr 2018 01:01:59 +0200 Subject: [PATCH] Rename SmtpTransportBuilder to SmtpClient --- README.md | 6 +- lettre/benches/transport_smtp.rs | 2 +- lettre/examples/smtp.rs | 6 +- lettre/src/lib.rs | 2 +- lettre/src/smtp/client/mod.rs | 10 +-- lettre/src/smtp/mod.rs | 88 ++++++++++-------------- lettre/tests/transport_smtp.rs | 11 +-- lettre_email/examples/smtp.rs | 6 +- lettre_email/src/lib.rs | 2 +- website/content/sending-messages/smtp.md | 14 ++-- 10 files changed, 65 insertions(+), 82 deletions(-) diff --git a/README.md b/README.md index ebc3618..943c8fb 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,7 @@ extern crate lettre; extern crate lettre_email; extern crate mime; -use lettre::{Transport, SmtpTransport}; +use lettre::{Transport, SmtpClient}; use lettre_email::Email; use std::path::Path; @@ -65,8 +65,8 @@ fn main() { .unwrap(); // Open a local connection on port 25 - let mut mailer = SmtpTransport::builder_unencrypted_localhost().unwrap() - .build(); + let mut mailer = SmtpClient::new_unencrypted_localhost().unwrap() + .transport(); // Send the email let result = mailer.send(email.into()); diff --git a/lettre/benches/transport_smtp.rs b/lettre/benches/transport_smtp.rs index bc8a888..0b2d7c1 100644 --- a/lettre/benches/transport_smtp.rs +++ b/lettre/benches/transport_smtp.rs @@ -3,7 +3,7 @@ extern crate lettre; extern crate test; -use lettre::{ClientSecurity, SmtpTransport, Envelope}; +use lettre::{ClientSecurity, Envelope, SmtpTransport}; use lettre::{EmailAddress, SendableEmail, Transport}; use lettre::smtp::ConnectionReuseParameters; diff --git a/lettre/examples/smtp.rs b/lettre/examples/smtp.rs index 45a475b..c75a1fa 100644 --- a/lettre/examples/smtp.rs +++ b/lettre/examples/smtp.rs @@ -1,7 +1,7 @@ extern crate env_logger; extern crate lettre; -use lettre::{EmailAddress, Envelope, SendableEmail, SmtpTransport, Transport}; +use lettre::{EmailAddress, Envelope, SendableEmail, SmtpClient, Transport}; fn main() { env_logger::init(); @@ -16,9 +16,7 @@ fn main() { ); // Open a local connection on port 25 - let mut mailer = SmtpTransport::builder_unencrypted_localhost() - .unwrap() - .build(); + let mut mailer = SmtpClient::new_unencrypted_localhost().unwrap().transport(); // Send the email let result = mailer.send(email); diff --git a/lettre/src/lib.rs b/lettre/src/lib.rs index 4f97356..b120073 100644 --- a/lettre/src/lib.rs +++ b/lettre/src/lib.rs @@ -46,7 +46,7 @@ pub use file::FileTransport; #[cfg(feature = "sendmail-transport")] pub use sendmail::SendmailTransport; #[cfg(feature = "smtp-transport")] -pub use smtp::{ClientSecurity, SmtpTransport}; +pub use smtp::{ClientSecurity, SmtpClient, SmtpTransport}; #[cfg(feature = "smtp-transport")] pub use smtp::client::net::ClientTlsParameters; use std::fmt::{self, Display, Formatter}; diff --git a/lettre/src/smtp/client/mod.rs b/lettre/src/smtp/client/mod.rs index 402a6c6..8439ebb 100644 --- a/lettre/src/smtp/client/mod.rs +++ b/lettre/src/smtp/client/mod.rs @@ -77,7 +77,7 @@ fn escape_crlf(string: &str) -> String { /// Structure that implements the SMTP client #[derive(Debug, Default)] -pub struct Client { +pub struct InnerClient { /// TCP stream between client and server /// Value is None before connection stream: Option>, @@ -90,16 +90,16 @@ macro_rules! return_err ( ); #[cfg_attr(feature = "cargo-clippy", allow(new_without_default_derive))] -impl Client { +impl InnerClient { /// Creates a new SMTP client /// /// It does not connects to the server, but only creates the `Client` - pub fn new() -> Client { - Client { stream: None } + pub fn new() -> InnerClient { + InnerClient { stream: None } } } -impl Client { +impl InnerClient { /// Closes the SMTP transaction if possible pub fn close(&mut self) { let _ = self.command(QuitCommand); diff --git a/lettre/src/smtp/mod.rs b/lettre/src/smtp/mod.rs index c8aff15..b99172b 100644 --- a/lettre/src/smtp/mod.rs +++ b/lettre/src/smtp/mod.rs @@ -18,7 +18,7 @@ use {SendableEmail, Transport}; use native_tls::TlsConnector; use smtp::authentication::{Credentials, Mechanism, DEFAULT_ENCRYPTED_MECHANISMS, DEFAULT_UNENCRYPTED_MECHANISMS}; -use smtp::client::Client; +use smtp::client::InnerClient; use smtp::client::net::ClientTlsParameters; use smtp::client::net::DEFAULT_TLS_PROTOCOLS; use smtp::commands::*; @@ -91,7 +91,7 @@ pub enum ConnectionReuseParameters { /// Contains client configuration #[allow(missing_debug_implementations)] -pub struct SmtpTransportBuilder { +pub struct SmtpClient { /// Enable connection reuse connection_reuse: ConnectionReuseParameters, /// Name sent during EHLO @@ -112,7 +112,7 @@ pub struct SmtpTransportBuilder { } /// Builder for the SMTP `SmtpTransport` -impl SmtpTransportBuilder { +impl SmtpClient { /// Creates a new SMTP client /// /// Defaults are: @@ -121,14 +121,11 @@ impl SmtpTransportBuilder { /// * No authentication /// * No SMTPUTF8 support /// * A 60 seconds timeout for smtp commands - pub fn new( - addr: A, - security: ClientSecurity, - ) -> Result { + pub fn new(addr: A, security: ClientSecurity) -> Result { let mut addresses = addr.to_socket_addrs()?; match addresses.next() { - Some(addr) => Ok(SmtpTransportBuilder { + Some(addr) => Ok(SmtpClient { server_addr: addr, security, smtp_utf8: false, @@ -142,41 +139,59 @@ impl SmtpTransportBuilder { } } + /// Simple and secure transport, should be used when possible. + /// Creates an encrypted transport over submission port, using the provided domain + /// to validate TLS certificates. + pub fn new_simple(domain: &str) -> Result { + let mut tls_builder = TlsConnector::builder()?; + tls_builder.supported_protocols(DEFAULT_TLS_PROTOCOLS)?; + + let tls_parameters = + ClientTlsParameters::new(domain.to_string(), tls_builder.build().unwrap()); + + SmtpClient::new( + (domain, SUBMISSION_PORT), + ClientSecurity::Required(tls_parameters), + ) + } + + /// Creates a new local SMTP client to port 25 + pub fn new_unencrypted_localhost() -> Result { + SmtpClient::new(("localhost", SMTP_PORT), ClientSecurity::None) + } + /// Enable SMTPUTF8 if the server supports it - pub fn smtp_utf8(mut self, enabled: bool) -> SmtpTransportBuilder { + pub fn smtp_utf8(mut self, enabled: bool) -> SmtpClient { self.smtp_utf8 = enabled; self } /// Set the name used during EHLO - pub fn hello_name(mut self, name: ClientId) -> SmtpTransportBuilder { + pub fn hello_name(mut self, name: ClientId) -> SmtpClient { self.hello_name = name; self } /// Enable connection reuse - pub fn connection_reuse( - mut self, - parameters: ConnectionReuseParameters, - ) -> SmtpTransportBuilder { + pub fn connection_reuse(mut self, parameters: ConnectionReuseParameters) -> SmtpClient { self.connection_reuse = parameters; self } /// Set the client credentials - pub fn credentials>(mut self, credentials: S) -> SmtpTransportBuilder { + pub fn credentials>(mut self, credentials: S) -> SmtpClient { self.credentials = Some(credentials.into()); self } /// Set the authentication mechanism to use - pub fn authentication_mechanism(mut self, mechanism: Mechanism) -> SmtpTransportBuilder { + pub fn authentication_mechanism(mut self, mechanism: Mechanism) -> SmtpClient { self.authentication_mechanism = Some(mechanism); self } /// Set the timeout duration - pub fn timeout(mut self, timeout: Option) -> SmtpTransportBuilder { + pub fn timeout(mut self, timeout: Option) -> SmtpClient { self.timeout = timeout; self } @@ -184,7 +199,7 @@ impl SmtpTransportBuilder { /// Build the SMTP client /// /// It does not connect to the server, but only creates the `SmtpTransport` - pub fn build(self) -> SmtpTransport { + pub fn transport(self) -> SmtpTransport { SmtpTransport::new(self) } } @@ -207,9 +222,9 @@ pub struct SmtpTransport { /// SmtpTransport variable states state: State, /// Information about the client - client_info: SmtpTransportBuilder, + client_info: SmtpClient, /// Low level client - client: Client, + client: InnerClient, } macro_rules! try_smtp ( @@ -228,40 +243,11 @@ macro_rules! try_smtp ( ); impl<'a> SmtpTransport { - /// Simple and secure transport, should be used when possible. - /// Creates an encrypted transport over submission port, using the provided domain - /// to validate TLS certificates. - pub fn simple_builder(domain: &str) -> Result { - let mut tls_builder = TlsConnector::builder()?; - tls_builder.supported_protocols(DEFAULT_TLS_PROTOCOLS)?; - - let tls_parameters = - ClientTlsParameters::new(domain.to_string(), tls_builder.build().unwrap()); - - SmtpTransportBuilder::new( - (domain, SUBMISSION_PORT), - ClientSecurity::Required(tls_parameters), - ) - } - - /// Creates a new configurable builder - pub fn builder( - addr: A, - security: ClientSecurity, - ) -> Result { - SmtpTransportBuilder::new(addr, security) - } - - /// Creates a new local SMTP client to port 25 - pub fn builder_unencrypted_localhost() -> Result { - SmtpTransportBuilder::new(("localhost", SMTP_PORT), ClientSecurity::None) - } - /// Creates a new SMTP client /// /// It does not connect to the server, but only creates the `SmtpTransport` - pub fn new(builder: SmtpTransportBuilder) -> SmtpTransport { - let client = Client::new(); + pub fn new(builder: SmtpClient) -> SmtpTransport { + let client = InnerClient::new(); SmtpTransport { client, diff --git a/lettre/tests/transport_smtp.rs b/lettre/tests/transport_smtp.rs index d0174d7..ff7c31c 100644 --- a/lettre/tests/transport_smtp.rs +++ b/lettre/tests/transport_smtp.rs @@ -3,13 +3,10 @@ extern crate lettre; #[cfg(test)] #[cfg(feature = "smtp-transport")] mod test { - use lettre::{ClientSecurity, EmailAddress, Envelope, SendableEmail, SmtpTransport, Transport}; + use lettre::{ClientSecurity, EmailAddress, Envelope, SendableEmail, SmtpClient, Transport}; #[test] fn smtp_transport_simple() { - let mut sender = SmtpTransport::builder("127.0.0.1:2525", ClientSecurity::None) - .unwrap() - .build(); let email = SendableEmail::new( Envelope::new( Some(EmailAddress::new("user@localhost".to_string()).unwrap()), @@ -19,7 +16,11 @@ mod test { "Hello ß☺ example".to_string().into_bytes(), ); - sender.send(email).unwrap(); + SmtpClient::new("127.0.0.1:2525", ClientSecurity::None) + .unwrap() + .transport() + .send(email) + .unwrap(); } } diff --git a/lettre_email/examples/smtp.rs b/lettre_email/examples/smtp.rs index c10d0fe..bd3b879 100644 --- a/lettre_email/examples/smtp.rs +++ b/lettre_email/examples/smtp.rs @@ -2,7 +2,7 @@ extern crate lettre; extern crate lettre_email; extern crate mime; -use lettre::{SmtpTransport, Transport}; +use lettre::{SmtpClient, Transport}; use lettre_email::Email; use std::path::Path; @@ -19,9 +19,7 @@ fn main() { .unwrap(); // Open a local connection on port 25 - let mut mailer = SmtpTransport::builder_unencrypted_localhost() - .unwrap() - .build(); + let mut mailer = SmtpClient::new_unencrypted_localhost().unwrap().transport(); // Send the email let result = mailer.send(email.into()); diff --git a/lettre_email/src/lib.rs b/lettre_email/src/lib.rs index f2c0f7e..8bdbdf9 100644 --- a/lettre_email/src/lib.rs +++ b/lettre_email/src/lib.rs @@ -452,7 +452,7 @@ impl EmailBuilder { #[cfg(test)] mod test { - use super::{SendableEmail, EmailBuilder}; + use super::{EmailBuilder, SendableEmail}; use lettre::EmailAddress; use time::now; diff --git a/website/content/sending-messages/smtp.md b/website/content/sending-messages/smtp.md index 4cfaf47..9adb7ef 100644 --- a/website/content/sending-messages/smtp.md +++ b/website/content/sending-messages/smtp.md @@ -20,7 +20,7 @@ This is the most basic example of usage: ```rust,no_run extern crate lettre; -use lettre::{SendableEmail, EmailAddress, Transport, Envelope, SmtpTransport}; +use lettre::{SendableEmail, EmailAddress, Transport, Envelope, SmtpClient}; fn main() { let email = SendableEmail::new( @@ -34,7 +34,7 @@ fn main() { // Open a local connection on port 25 let mut mailer = - SmtpTransport::builder_unencrypted_localhost().unwrap().build(); + SmtpClient::new_unencrypted_localhost().unwrap().transport(); // Send the email let result = mailer.send(email); @@ -48,7 +48,7 @@ fn main() { extern crate lettre; use lettre::smtp::authentication::{Credentials, Mechanism}; -use lettre::{SendableEmail, Envelope, EmailAddress, Transport, SmtpTransport}; +use lettre::{SendableEmail, Envelope, EmailAddress, Transport, SmtpClient}; use lettre::smtp::extension::ClientId; use lettre::smtp::ConnectionReuseParameters; @@ -72,7 +72,7 @@ fn main() { ); // Connect to a remote server on a custom port - let mut mailer = SmtpTransport::simple_builder("server.tld").unwrap() + let mut mailer = SmtpClient::new_simple("server.tld").unwrap() // Set the name sent during EHLO/HELO, default is `localhost` .hello_name(ClientId::Domain("my.hostname.tld".to_string())) // Add credentials for authentication @@ -82,7 +82,7 @@ fn main() { // Configure expected authentication mechanism .authentication_mechanism(Mechanism::Plain) // Enable connection reuse - .connection_reuse(ConnectionReuseParameters::ReuseUnlimited).build(); + .connection_reuse(ConnectionReuseParameters::ReuseUnlimited).transport(); let result_1 = mailer.send(email_1); assert!(result_1.is_ok()); @@ -106,13 +106,13 @@ extern crate lettre; use lettre::EmailAddress; use lettre::smtp::SMTP_PORT; -use lettre::smtp::client::Client; +use lettre::smtp::client::InnerClient; use lettre::smtp::client::net::NetworkStream; use lettre::smtp::extension::ClientId; use lettre::smtp::commands::*; fn main() { - let mut email_client: Client = Client::new(); + let mut email_client: InnerClient = InnerClient::new(); let _ = email_client.connect(&("localhost", SMTP_PORT), None); let _ = email_client.command(EhloCommand::new(ClientId::new("my_hostname".to_string()))); let _ = email_client.command(