1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241
//! Mailstrom handles email delivery in a background worker thread, with the following //! features: //! //! * Accepts an email from the caller and then does everything necessary to get it //! delivered to all recipients without blocking the caller. //! * Allows the caller to query the status of an earlier submitted email at any time, //! to determine if it is Queued, Delivered, Deferred, or has Failed, with details //! as to why, on a per-recipient basis. //! * Handles all parsing, validation, and encoding of email content and headers, //! in compliance with RFC 5322 (and other RFCs). Uses the //! [email-format](https://github.com/mikedilger/email-format) library for this. //! * Looks up the DNS MX records of the recipients, and delivers directly to those Internet //! mail servers over SMTP, thus not requiring any local SMTP relay. Uses the //! [trust-dns](https://github.com/bluejekyll/trust-dns) library for DNS lookups //! * SMTP transport "heavy lifting" is performed via the [lettre](https://github.com/lettre/lettre) //! library. Uses STARTTLS where available. //! * Retries with exponential backoff for a fixed number of retries (currently fixed at 3), //! when the send result is Deferred //! * Uses a pluggable user-defined state management (persistence) layer. //! //! ## Limitations //! //! * The [email-format](https://github.com/mikedilger/email-format) crate is somewhat incomplete //! and clunky still. It doesn't incorporate RFC 6854 (updated From and Sender syntax) yet. //! It defines types one-to-one with ABNF parsing units, rather than as semantic units of meaning. //! And it doesn't let you use obvious types yet like setting the date from a `DateTime` type. //! However, these issues will be worked out in the near future. //! //! You can use it as follows: //! //! ```no_run //! extern crate email_format; //! extern crate mailstrom; //! //! use email_format::Email; //! use mailstrom::{Mailstrom, Config, MemoryStorage}; //! //! fn main() { //! let mut email = Email::new( //! "myself@mydomain.com", // "From:" //! "Wed, 05 Jan 2015 15:13:05 +1300" // "Date:" //! ).unwrap(); //! //! email.set_bcc("myself@mydomain.com").unwrap(); //! email.set_sender("from_myself@mydomain.com").unwrap(); //! email.set_reply_to("My Mailer <no-reply@mydomain.com>").unwrap(); //! email.set_to("You <you@yourdomain.com>, AndYou <andyou@yourdomain.com>").unwrap(); //! email.set_cc("Our Friend <friend@frienddomain.com>").unwrap(); //! email.set_subject("Hello Friend").unwrap(); //! email.set_body("Good to hear from you.\r\n\ //! I wish you the best.\r\n\ //! \r\n\ //! Your Friend").unwrap(); //! //! let mut mailstrom = Mailstrom::new( //! Config { //! helo_name: "my.host.domainname".to_owned(), //! ..Default::default() //! }, //! MemoryStorage::new()); //! //! // We must explicitly tell mailstrom to start actually sending emails. If we //! // were only interested in reading the status of previously sent emails, we //! // would not send this command. //! mailstrom.start().unwrap(); //! //! let message_id = mailstrom.send_email(email).unwrap(); //! //! // Later on, after the worker thread has had time to process the request, //! // you can check the status: //! //! let status = mailstrom.query_status(&*message_id).unwrap(); //! println!("{:?}", status); //! } //! ``` #![feature(integer_atomics)] extern crate uuid; extern crate email_format; extern crate trust_dns_resolver; extern crate lettre; #[macro_use] extern crate log; #[macro_use] extern crate serde_derive; extern crate native_tls; #[cfg(test)] mod tests; mod config; pub use config::Config; mod worker; pub use worker::WorkerStatus; pub mod error; mod delivery_result; pub use delivery_result::DeliveryResult; mod recipient_status; pub use recipient_status::RecipientStatus; pub mod message_status; pub use message_status::MessageStatus; pub mod prepared_email; pub use prepared_email::PreparedEmail; mod storage; use std::sync::{mpsc, Arc, RwLock}; use std::sync::atomic::{AtomicU8, Ordering}; use std::thread; use std::ops::Drop; use email_format::Email; use worker::{Worker, Message}; use error::Error; pub use message_status::InternalMessageStatus; pub use storage::{MailstromStorage, MailstromStorageError, MemoryStorage}; pub struct Mailstrom<S: MailstromStorage + 'static> { config: Config, sender: mpsc::Sender<Message>, worker_status: Arc<AtomicU8>, storage: Arc<RwLock<S>>, } impl<S: MailstromStorage + 'static> Mailstrom<S> { /// Create a new Mailstrom instance for sending emails. pub fn new(config: Config, storage: S) -> Mailstrom<S> { let (sender, receiver) = mpsc::channel(); let storage = Arc::new(RwLock::new(storage)); let worker_status = Arc::new(AtomicU8::new(WorkerStatus::Ok as u8)); let mut worker = Worker::new(receiver, Arc::clone(&storage), Arc::clone(&worker_status), config.clone()); let _ = thread::spawn(move|| { worker.run(); }); Mailstrom { config: config, sender: sender, worker_status: worker_status, storage: storage, } } /// Mailstrom requires an explicit start command to start sending emails. This is /// because some clients are only interested in reading the status of sent emails, /// and will terminate before any real sending can be accomplished. pub fn start(&mut self) -> Result<(), Error> { try!(self.sender.send(Message::Start)); Ok(()) } /// Ask Mailstrom to die. This is not required, you can simply let it fall out /// of scope and it will clean itself up. pub fn die(&mut self) -> Result<(), Error> { try!(self.sender.send(Message::Terminate)); Ok(()) } /// Determine the status of the worker pub fn worker_status(&self) -> WorkerStatus { WorkerStatus::from_u8(self.worker_status.load(Ordering::SeqCst)) } /// Send an email, getting back it's message-id pub fn send_email(&mut self, email: Email) -> Result<String, Error> { let (prepared_email, internal_message_status) = ::prepared_email::prepare_email(email, &*self.config.helo_name)?; let message_id = internal_message_status.message_id.clone(); { // Lock the storage let mut guard = match (*self.storage).write() { Ok(guard) => guard, Err(_) => return Err(Error::Lock), }; // Store the email try!((*guard).store(prepared_email, internal_message_status)); } try!(self.sender.send(Message::SendEmail(message_id.clone()))); info!("Passed email {} off to worker", &*message_id); Ok(message_id) } // Query Status of email pub fn query_status(&mut self, message_id: &str) -> Result<MessageStatus, Error> { let guard = match (*self.storage).read() { Ok(guard) => guard, Err(_) => return Err(Error::Lock), }; let status = try!((*guard).retrieve_status(message_id)); Ok(status.as_message_status()) } // Query recently queued and sent emails. This includes all emails where sending is not // yet complete, and also all emails where sending is complete but for which they have // not yet been reported on (via this function). pub fn query_recent(&mut self) -> Result<Vec<MessageStatus>, Error> { let mut guard = match (*self.storage).write() { Ok(guard) => guard, Err(_) => return Err(Error::Lock), }; let vec_statuses = try!((*guard).retrieve_all_recent()); Ok(vec_statuses.iter().map(|s| s.as_message_status()).collect()) } } impl<S: MailstromStorage + 'static> Drop for Mailstrom<S> { fn drop(&mut self) { info!("Mailstrom is terminating."); let _ = self.sender.send(Message::Terminate); } }