GSoC: finagle-smtp - initial

finagle-example/src/main/scala/com/twitter/finagle/example/smtp/Example.scala

@@ -0,0 +1,41 @@
+package com.twitter.finagle.example.smtp
+
+import com.twitter.logging.Logger
+import com.twitter.finagle.smtp._
+import com.twitter.finagle.SmtpSimple
+import com.twitter.util.{Await, Future}
+
+/**
+ * Simple SMTP client with an example of error handling.
+ */
+object Example {
+  private val log = Logger.get(getClass)
+
+  def main(args: Array[String]): Unit = {
+    // Raw text email
+    val email = DefaultEmail()
+      .from_("[email protected]")
+      .to_("[email protected]", "[email protected]")
+      .subject_("test")
+      .text("first line", "second line") //body is a sequence of lines
+
+    // Connect to a local SMTP server
+    val send = SmtpSimple.newService("localhost:2525")
+
+    // Send email
+    val res: Future[Unit] = send(email) onFailure {
+    // An error group
+    case ex: reply.SyntaxErrorReply => log.error("Syntax error: %s", ex.info)
+
+    // A concrete reply
+    case reply.ProcessingError(info) => log.error("Error processing request: %s", info)
+    }
+
+    log.info("Sending email...")
+
+    Await.ready(res)
+    send.close()
+
+    log.info("Sent")
+  }
+}

finagle-smtp/README.md

@@ -0,0 +1,90 @@
+# finagle-smtp
+
+This is a minimum implementation of SMTP client for finagle according to 
+[`RFC5321`][rfc]. The simplest guide to SMTP can be found, for example, [here][smtp2go].
+
+Note: There is no API yet in this implementation for creating 
+[`MIME`][mimewiki] messages, so the message should be plain US-ASCII text, or converted 
+to such. There is currently no support for any other SMTP extensions, either. This 
+functionality is to be added in future versions.
+
+[rfc]: http://tools.ietf.org/search/rfc5321
+[smtp2go]: http://www.smtp2go.com/articles/smtp-protocol
+[mimewiki]: http://en.wikipedia.org/wiki/MIME
+
+## Usage
+
+### Sending an email
+
+The object for instantiating a client capable of sending a simple email is `SmtpSimple`.
+For services created with it the request type is `EmailMessage`, described in 
+[`EmailMessage.scala`][EmailMessage].
+
+You can create an email using `EmailBuilder` class described in [`EmailBuilder.scala`][EmailBuilder]:
+
+```scala
+    val email = EmailBuilder()
+      .sender("[email protected]")
+      .to("[email protected]", "[email protected]")
+      .subject("test")
+      .bodyLines("first line", "second line") //body is a sequence of lines
+      .build
+```
+
+Applying the service on the email returns `Future.Done` in case of a successful operation.
+In case of failure it returns the first encountered error wrapped in a `Future`.
+
+[EmailMessage]: src/main/scala/com/twitter/finagle/smtp/EmailMessage.scala
+[EmailBuilder]: src/main/scala/com/twitter/finagle/smtp/EmailBuilder.scala
+
+#### Greeting and session
+
+Upon the connection the client receives server greeting.
+In the beginning of the session an EHLO request is sent automatically to identify the client.
+The session state is reset before every subsequent try.
+
+### Example
+
+The example of sending email to a local SMTP server with SmtpSimple and handling errors can be seen 
+in [`Example.scala`](src/main/scala/com/twitter/finagle/example/smtp/Example.scala).
+
+### Sending independent SMTP commands
+
+The object for instantiating an SMTP client capable of sending any command defined in *RFC5321* is `Smtp`. 
+
+For services created with it the request type is `Request`. Command classes are described in 
+[`Request.scala`][Request]. 
+
+Replies are differentiated by groups, which are described in [`ReplyGroups.scala`][ReplyGroups].
+The concrete reply types are case classes described in [`SmtpReplies.scala`][SmtpReplies].
+
+This allows flexible error handling:
+
+```scala
+val res = service(command) onFailure {
+  // An error group
+  case ex: SyntaxErrorReply => log.error("Syntax error: %s", ex.info)
+
+  // A concrete reply
+  case ProcessingError(info) => log,error("Error processing request: %s", info)
+
+  // Default
+  case _ => log.error("Error!")
+}
+
+// Or, another way:
+
+res handle {
+  ...
+}
+```
+
+[Request]: src/main/scala/com/twitter/finagle/smtp/Request.scala
+[ReplyGroups]: src/main/scala/com/twitter/finagle/smtp/reply/ReplyGroups.scala
+[SmtpReplies]: src/main/scala/com/twitter/finagle/smtp/reply/SmtpReplies.scala
+
+#### Greeting and session
+
+Default SMTP client only connects to the server and receives its greeting, but does not return greeting,
+as some commands may be executed without it. In case of malformed greeting the service is closed.
+Upon service.close() a quit command is sent automatically, if not sent earlier.

finagle-smtp/src/main/scala/com/twitter/finagle/Smtp.scala

@@ -0,0 +1,64 @@
+package com.twitter.finagle
+
+import com.twitter.finagle.client.{DefaultClient, Bridge}
+import com.twitter.finagle.smtp._
+import com.twitter.finagle.smtp.filter.{MailFilter, HeadersFilter, DataFilter}
+import com.twitter.finagle.smtp.reply._
+import com.twitter.finagle.smtp.transport.SmtpTransporter
+import com.twitter.util.{Time, Future}
+
+// TODO: switch to StackClient
+
+/**
+ * Implements an SMTP client. This type of client is capable of sending
+ * separate SMTP commands and receiving replies to them.
+ */
+object Smtp extends Client[Request, Reply]{
+
+  private[this] val defaultClient = DefaultClient[Request, Reply] (
+    name = "smtp",
+    endpointer = {
+      val bridge = Bridge[Request, UnspecifiedReply, Request, Reply](
+        SmtpTransporter, new SmtpClientDispatcher(_)
+      )
+      (addr, stats) => bridge(addr, stats)
+    })
+
+  /**
+   * Constructs an SMTP client.
+   *
+   * Upon closing the connection this client sends QUIT command;
+   * it also performs dot stuffing.
+   */
+  override def newClient(dest: Name, label: String): ServiceFactory[Request, Reply] = {
+    DataFilter andThen defaultClient.newClient(dest, label)
+  }
+}
+
+/**
+ * Implements an SMTP client that can send an [[com.twitter.finagle.smtp.EmailMessage]].
+ * The application of this client's service returns [[com.twitter.util.Future.Done]]
+ * in case of success or the first encountered error in case of a failure.
+ */
+object SmtpSimple extends Client[EmailMessage, Unit] {
+  /**
+  * Constructs an SMTP client that sends a hello request
+  * in the beginning of the session to identify itself;
+  * it also copies email headers into the body of the message.
+  * The dot stuffing and connection closing
+  * behaviour is the same as in [[com.twitter.finagle.Smtp.newClient()]].
+  */
+  override def newClient(dest: Name, label: String): ServiceFactory[EmailMessage, Unit] = {
+    val startHelloClient = new ServiceFactoryProxy[Request, Reply](Smtp.newClient(dest, label)) {
+      override def apply(conn: ClientConnection) = {
+        self.apply(conn) flatMap { service =>
+          service(Request.Hello)
+          Future.value(service)
+        }
+      }
+    }
+    HeadersFilter andThen MailFilter andThen startHelloClient
+  }
+}
+
+