Merge pull request #4 from jeddenlea/master

Merging pull request
- Attachments is now a slice
- Speed/Memory optimizations

email.go

@@ -1,5 +1,5 @@
-//Package email is designed to provide an "email interface for humans."
-//Designed to be robust and flexible, the email package aims to make sending email easy without getting in the way.
+// Package email is designed to provide an "email interface for humans."
+// Designed to be robust and flexible, the email package aims to make sending email easy without getting in the way.
 package email
 
 import (
@@ -14,84 +14,81 @@ import (
 	"net/smtp"
 	"net/textproto"
 	"os"
+	"path"
 	"path/filepath"
 	"strings"
 )
 
 const (
-	//MaxLineLength is the maximum line length per RFC 2045
+	// MaxLineLength is the maximum line length per RFC 2045
 	MaxLineLength = 76
 )
 
-//Email is the type used for email messages
+// Email is the type used for email messages
 type Email struct {
 	From        string
 	To          []string
 	Bcc         []string
 	Cc          []string
 	Subject     string
-	Text        string //Plaintext message (optional)
-	HTML        string //Html message (optional)
+	Text        string // Plaintext message (optional)
+	HTML        string // Html message (optional)
 	Headers     textproto.MIMEHeader
-	Attachments map[string]*Attachment
+	Attachments []*Attachment
 	ReadReceipt []string
 }
 
-//NewEmail creates an Email, and returns the pointer to it.
+// NewEmail creates an Email, and returns the pointer to it.
 func NewEmail() *Email {
-	return &Email{Attachments: make(map[string]*Attachment), Headers: textproto.MIMEHeader{}}
+	return &Email{Headers: textproto.MIMEHeader{}}
 }
 
-//Attach is used to attach content from an io.Reader to the email.
-//Required parameters include an io.Reader, the desired filename for the attachment, and the Content-Type
-//The function will return the created Attachment for reference, as well as nil for the error, if successful.
+// Attach is used to attach content from an io.Reader to the email.
+// Required parameters include an io.Reader, the desired filename for the attachment, and the Content-Type
+// The function will return the created Attachment for reference, as well as nil for the error, if successful.
 func (e *Email) Attach(r io.Reader, filename string, c string) (a *Attachment, err error) {
-	buffer := new(bytes.Buffer)
-	_, err = buffer.ReadFrom(r)
-	if err != nil {
-		return nil, err
+	var buffer bytes.Buffer
+	if _, err = io.Copy(&buffer, r); err != nil {
+		return
 	}
-	e.Attachments[filename] = &Attachment{
+	at := &Attachment{
 		Filename: filename,
 		Header:   textproto.MIMEHeader{},
-		Content:  buffer.Bytes()}
-	at := e.Attachments[filename]
-	//Get the Content-Type to be used in the MIMEHeader
+		Content:  buffer.Bytes(),
+	}
+	// Get the Content-Type to be used in the MIMEHeader
 	if c != "" {
 		at.Header.Set("Content-Type", c)
 	} else {
-		//If the Content-Type is blank, set the Content-Type to "application/octet-stream"
+		// If the Content-Type is blank, set the Content-Type to "application/octet-stream"
 		at.Header.Set("Content-Type", "application/octet-stream")
 	}
 	at.Header.Set("Content-Disposition", fmt.Sprintf("attachment;\r\n filename=\"%s\"", filename))
 	at.Header.Set("Content-Transfer-Encoding", "base64")
+	e.Attachments = append(e.Attachments, at)
 	return at, nil
 }
 
-//AttachFile is used to attach content to the email.
-//It attempts to open the file referenced by filename and, if successful, creates an Attachment.
-//This Attachment is then appended to the slice of Email.Attachments.
-//The function will then return the Attachment for reference, as well as nil for the error, if successful.
+// AttachFile is used to attach content to the email.
+// It attempts to open the file referenced by filename and, if successful, creates an Attachment.
+// This Attachment is then appended to the slice of Email.Attachments.
+// The function will then return the Attachment for reference, as well as nil for the error, if successful.
 func (e *Email) AttachFile(filename string) (a *Attachment, err error) {
-	//Check if the file exists, return any error
-	if _, err := os.Stat(filename); os.IsNotExist(err) {
-		return nil, err
-	}
 	f, err := os.Open(filename)
 	if err != nil {
-		return nil, err
+		return
 	}
-	//Get the Content-Type to be used in the MIMEHeader
 	ct := mime.TypeByExtension(filepath.Ext(filename))
-	return e.Attach(f, filename, ct)
+	basename := path.Base(filename)
+	return e.Attach(f, basename, ct)
 }
 
-//Bytes converts the Email object to a []byte representation, including all needed MIMEHeaders, boundaries, etc.
+// Bytes converts the Email object to a []byte representation, including all needed MIMEHeaders, boundaries, etc.
 func (e *Email) Bytes() ([]byte, error) {
 	buff := &bytes.Buffer{}
 	w := multipart.NewWriter(buff)
-	//Set the appropriate headers (overwriting any conflicts)
-	//Leave out Bcc (only included in envelope headers)
+	// Set the appropriate headers (overwriting any conflicts)
+	// Leave out Bcc (only included in envelope headers)
 	e.Headers.Set("To", strings.Join(e.To, ","))
 	if e.Cc != nil {
 		e.Headers.Set("Cc", strings.Join(e.Cc, ","))
@@ -104,22 +101,23 @@ func (e *Email) Bytes() ([]byte, error) {
 	e.Headers.Set("MIME-Version", "1.0")
 	e.Headers.Set("Content-Type", fmt.Sprintf("multipart/mixed;\r\n boundary=%s\r\n", w.Boundary()))
 
-	//Write the envelope headers (including any custom headers)
+	// Write the envelope headers (including any custom headers)
 	if err := headerToBytes(buff, e.Headers); err != nil {
+		return nil, fmt.Errorf("Failed to render message headers: %s", err)
 	}
-	//Start the multipart/mixed part
+	// Start the multipart/mixed part
 	fmt.Fprintf(buff, "--%s\r\n", w.Boundary())
 	header := textproto.MIMEHeader{}
-	//Check to see if there is a Text or HTML field
+	// Check to see if there is a Text or HTML field
 	if e.Text != "" || e.HTML != "" {
 		subWriter := multipart.NewWriter(buff)
-		//Create the multipart alternative part
+		// Create the multipart alternative part
 		header.Set("Content-Type", fmt.Sprintf("multipart/alternative;\r\n boundary=%s\r\n", subWriter.Boundary()))
-		//Write the header
+		// Write the header
 		if err := headerToBytes(buff, header); err != nil {
-
+			return nil, fmt.Errorf("Failed to render multipart message headers: %s", err)
 		}
-		//Create the body sections
+		// Create the body sections
 		if e.Text != "" {
 			header.Set("Content-Type", fmt.Sprintf("text/plain; charset=UTF-8"))
 			header.Set("Content-Transfer-Encoding", "quoted-printable")
@@ -146,16 +144,14 @@ func (e *Email) Bytes() ([]byte, error) {
 			return nil, err
 		}
 	}
-	//Create attachment part, if necessary
-	if e.Attachments != nil {
-		for _, a := range e.Attachments {
-			ap, err := w.CreatePart(a.Header)
-			if err != nil {
-				return nil, err
-			}
-			//Write the base64Wrapped content to the part
-			base64Wrap(ap, a.Content)
+	// Create attachment part, if necessary
+	for _, a := range e.Attachments {
+		ap, err := w.CreatePart(a.Header)
+		if err != nil {
+			return nil, err
 		}
+		// Write the base64Wrapped content to the part
+		base64Wrap(ap, a.Content)
 	}
 	if err := w.Close(); err != nil {
 		return nil, err
@@ -163,15 +159,16 @@ func (e *Email) Bytes() ([]byte, error) {
 	return buff.Bytes(), nil
 }
 
-//Send an email using the given host and SMTP auth (optional), returns any error thrown by smtp.SendMail
-//This function merges the To, Cc, and Bcc fields and calls the smtp.SendMail function using the Email.Bytes() output as the message
+// Send an email using the given host and SMTP auth (optional), returns any error thrown by smtp.SendMail
+// This function merges the To, Cc, and Bcc fields and calls the smtp.SendMail function using the Email.Bytes() output as the message
 func (e *Email) Send(addr string, a smtp.Auth) error {
-	//Check to make sure there is at least one recipient and one "From" address
-	if e.From == "" || (len(e.To) == 0 && len(e.Cc) == 0 && len(e.Bcc) == 0) {
+	// Merge the To, Cc, and Bcc fields
+	to := make([]string, 0, len(e.To)+len(e.Cc)+len(e.Bcc))
+	to = append(append(append(to, e.To...), e.Cc...), e.Bcc...)
+	// Check to make sure there is at least one recipient and one "From" address
+	if e.From == "" || len(to) == 0 {
 		return errors.New("Must specify at least one From address and one To address")
 	}
-	// Merge the To, Cc, and Bcc fields
-	to := append(append(e.To, e.Cc...), e.Bcc...)
 	from, err := mail.ParseAddress(e.From)
 	if err != nil {
 		return err
@@ -183,78 +180,104 @@ func (e *Email) Send(addr string, a smtp.Auth) error {
 	return smtp.SendMail(addr, a, from.Address, to, raw)
 }
 
-//Attachment is a struct representing an email attachment.
-//Based on the mime/multipart.FileHeader struct, Attachment contains the name, MIMEHeader, and content of the attachment in question
+// Attachment is a struct representing an email attachment.
+// Based on the mime/multipart.FileHeader struct, Attachment contains the name, MIMEHeader, and content of the attachment in question
 type Attachment struct {
 	Filename string
 	Header   textproto.MIMEHeader
 	Content  []byte
 }
 
-//quotePrintEncode writes the quoted-printable text to the IO Writer (according to RFC 2045)
+// quotePrintEncode writes the quoted-printable text to the IO Writer (according to RFC 2045)
 func quotePrintEncode(w io.Writer, s string) error {
+	var buf [3]byte
 	mc := 0
-	for _, c := range s {
-		// Handle the soft break for the EOL, if needed
-		if mc == MaxLineLength-1 || (!isPrintable(c) && mc+len(fmt.Sprintf("%s%X", "=", c)) > MaxLineLength-1) {
-			if _, err := fmt.Fprintf(w, "%s", "=\r\n"); err != nil {
-				return err
-			}
+	for i := 0; i < len(s); i++ {
+		c := s[i]
+		// We're assuming Unix style text formats as input (LF line break), and
+		// quoted-printble uses CRLF line breaks. (Literal CRs will become
+		// "=0D", but probably shouldn't be there to begin with!)
+		if c == '\n' {
+			io.WriteString(w, "\r\n")
 			mc = 0
+			continue
 		}
-		//append the appropriate character
+
+		var nextOut []byte
 		if isPrintable(c) {
-			//Printable character
-			if _, err := fmt.Fprintf(w, "%s", string(c)); err != nil {
-				return err
-			}
-			// Reset the counter if we wrote a newline
-			if c == '\n' {
-				mc = 0
-			}
-			mc++
-			continue
+			nextOut = append(buf[:0], c)
 		} else {
-			//non-printable.. encode it (TODO)
-			es := fmt.Sprintf("%s%X", "=", c)
-			if _, err := fmt.Fprintf(w, "%s", es); err != nil {
+			nextOut = buf[:]
+			qpEscape(nextOut, c)
+		}
+
+		// Add a soft line break if the next (encoded) byte would push this line
+		// to or past the limit.
+		if mc+len(nextOut) >= MaxLineLength {
+			if _, err := io.WriteString(w, "=\r\n"); err != nil {
 				return err
 			}
-			//todo - increment correctly
-			mc += len(es)
+			mc = 0
 		}
+
+		if _, err := w.Write(nextOut); err != nil {
+			return err
+		}
+		mc += len(nextOut)
+	}
+	// No trailing end-of-line?? Soft line break, then. TODO: is this sane?
+	if mc > 0 {
+		io.WriteString(w, "=\r\n")
 	}
 	return nil
 }
 
-//isPrintable returns true if the rune given is "printable" according to RFC 2045, false otherwise
-func isPrintable(c rune) bool {
+// isPrintable returns true if the rune given is "printable" according to RFC 2045, false otherwise
+func isPrintable(c byte) bool {
 	return (c >= '!' && c <= '<') || (c >= '>' && c <= '~') || (c == ' ' || c == '\n' || c == '\t')
 }
 
-//base64Wrap encodeds the attachment content, and wraps it according to RFC 2045 standards (every 76 chars)
-//The output is then written to the specified io.Writer
+// qpEscape is a helper function for quotePrintEncode which escapes a
+// non-printable byte. Expects len(dest) == 3.
+func qpEscape(dest []byte, c byte) {
+	const nums = "0123456789ABCDEF"
+	dest[0] = '='
+	dest[1] = nums[(c&0xf0)>>4]
+	dest[2] = nums[(c & 0xf)]
+}
+
+// base64Wrap encodeds the attachment content, and wraps it according to RFC 2045 standards (every 76 chars)
+// The output is then written to the specified io.Writer
 func base64Wrap(w io.Writer, b []byte) {
-	encoded := base64.StdEncoding.EncodeToString(b)
-	for i := 0; i < len(encoded); i += MaxLineLength {
-		//Do we need to print 76 characters, or the rest of the string?
-		if len(encoded)-i < MaxLineLength {
-			fmt.Fprintf(w, "%s\r\n", encoded[i:])
-		} else {
-			fmt.Fprintf(w, "%s\r\n", encoded[i:i+MaxLineLength])
-		}
+	// 57 raw bytes per 76-byte base64 line.
+	const maxRaw = 57
+	// Buffer for each line, including trailing CRLF.
+	var buffer [MaxLineLength + len("\r\n")]byte
+	copy(buffer[MaxLineLength:], "\r\n")
+	// Process raw chunks until there's no longer enough to fill a line.
+	for len(b) >= maxRaw {
+		base64.StdEncoding.Encode(buffer[:], b[:maxRaw])
+		w.Write(buffer[:])
+		b = b[maxRaw:]
+	}
+	// Handle the last chunk of bytes.
+	if len(b) > 0 {
+		out := buffer[:base64.StdEncoding.EncodedLen(len(b))]
+		base64.StdEncoding.Encode(out, b)
+		out = append(out, "\r\n"...)
+		w.Write(out)
 	}
 }
 
-//headerToBytes enumerates the key and values in the header, and writes the results to the IO Writer
+// headerToBytes enumerates the key and values in the header, and writes the results to the IO Writer
 func headerToBytes(w io.Writer, t textproto.MIMEHeader) error {
 	for k, v := range t {
-		//Write the header key
+		// Write the header key
 		_, err := fmt.Fprintf(w, "%s:", k)
 		if err != nil {
 			return err
 		}
-		//Write each value in the header
+		// Write each value in the header
 		for _, c := range v {
 			_, err := fmt.Fprintf(w, " %s\r\n", c)
 			if err != nil {

email_test.go

@@ -3,6 +3,10 @@ package email
 import (
 	"net/smtp"
 	"testing"
+
+	"bytes"
+	"crypto/rand"
+	"io/ioutil"
 )
 
 func TestEmail(*testing.T) {
@@ -32,3 +36,68 @@ func ExampleAttach() {
 	e := NewEmail()
 	e.AttachFile("test.txt")
 }
+
+func Test_base64Wrap(t *testing.T) {
+	file := "I'm a file long enough to force the function to wrap a\n" +
+		"couple of lines, but I stop short of the end of one line and\n" +
+		"have some padding dangling at the end."
+	encoded := "SSdtIGEgZmlsZSBsb25nIGVub3VnaCB0byBmb3JjZSB0aGUgZnVuY3Rpb24gdG8gd3JhcCBhCmNv\r\n" +
+		"dXBsZSBvZiBsaW5lcywgYnV0IEkgc3RvcCBzaG9ydCBvZiB0aGUgZW5kIG9mIG9uZSBsaW5lIGFu\r\n" +
+		"ZApoYXZlIHNvbWUgcGFkZGluZyBkYW5nbGluZyBhdCB0aGUgZW5kLg==\r\n"
+
+	var buf bytes.Buffer
+	base64Wrap(&buf, []byte(file))
+	if !bytes.Equal(buf.Bytes(), []byte(encoded)) {
+		t.Fatalf("Encoded file does not match expected: %#q != %#q", string(buf.Bytes()), encoded)
+	}
+}
+
+func Test_quotedPrintEncode(t *testing.T) {
+	var buf bytes.Buffer
+	text := "Dear reader!\n\n" +
+		"This is a test email to try and capture some of the corner cases that exist within\n" +
+		"the quoted-printable encoding.\n" +
+		"There are some wacky parts like =, and this input assumes UNIX line breaks so\r\n" +
+		"it can come out a little weird.  Also, we need to support unicode so here's a fish: 🐟\n"
+	expected := "Dear reader!\r\n\r\n" +
+		"This is a test email to try and capture some of the corner cases that exist=\r\n" +
+		" within\r\n" +
+		"the quoted-printable encoding.\r\n" +
+		"There are some wacky parts like =3D, and this input assumes UNIX line break=\r\n" +
+		"s so=0D\r\n" +
+		"it can come out a little weird.  Also, we need to support unicode so here's=\r\n" +
+		" a fish: =F0=9F=90=9F\r\n"
+
+	if err := quotePrintEncode(&buf, text); err != nil {
+		t.Fatal("quotePrintEncode: ", err)
+	}
+
+	if s := buf.String(); s != expected {
+		t.Errorf("quotedPrintEncode generated incorrect results: %#q != %#q", s, expected)
+	}
+}
+
+func Benchmark_quotedPrintEncode(b *testing.B) {
+	text := "Dear reader!\n\n" +
+		"This is a test email to try and capture some of the corner cases that exist within\n" +
+		"the quoted-printable encoding.\n" +
+		"There are some wacky parts like =, and this input assumes UNIX line breaks so\r\n" +
+		"it can come out a little weird.  Also, we need to support unicode so here's a fish: 🐟\n"
+
+	for i := 0; i <= b.N; i++ {
+		if err := quotePrintEncode(ioutil.Discard, text); err != nil {
+			panic(err)
+		}
+	}
+}
+
+func Benchmark_base64Wrap(b *testing.B) {
+	// Reasonable base case; 128K random bytes
+	file := make([]byte, 128*1024)
+	if _, err := rand.Read(file); err != nil {
+		panic(err)
+	}
+	for i := 0; i <= b.N; i++ {
+		base64Wrap(ioutil.Discard, file)
+	}
+}