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
//! 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);
//! }
//! ```

extern crate email_format;
extern crate lettre;
extern crate trust_dns_resolver;
extern crate uuid;
#[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 email_format::Email;
use std::ops::Drop;
use std::sync::{mpsc, Arc, RwLock};
use std::thread;

use error::Error;
pub use message_status::InternalMessageStatus;
pub use storage::{MailstromStorage, MailstromStorageError, MemoryStorage};
use worker::{Message, Worker};

pub struct Mailstrom<S: MailstromStorage + 'static> {
    config: Config,
    sender: mpsc::Sender<Message>,
    worker_status: Arc<RwLock<u8>>,
    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(RwLock::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 {
        let ws = *self.worker_status.read().unwrap();
        WorkerStatus::from_u8(ws)
    }

    /// Send an email, getting back its 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);
    }
}