mailcatcher2 0.10.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 04d793d679abdc3e5c257613b3c48471d4e31376cc1d6ce3f14f397b4bc0aff6
+  data.tar.gz: 7bbbc5203aafd9e2b28c6b93f612d950fdc3dc08e9885d7bcd89783d3cd380b4
+SHA512:
+  metadata.gz: 4eaf5d819d3663b4b7e60f2a079791686013a75a446ca7362a372189e5bdf52a8e9334c62e6c806c428f39f5789aa98d163f122106bd8b4813844c38fc2590dd
+  data.tar.gz: b1bc32114c69fc3c8b0de5ac063b133c8e33e523f714c84398ed2d5f23193287696746218819597d4bcad88056cea8e28e0fda59365bfbc256a525714f0f6df4

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010-2011 Samuel Cochran
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,176 @@
+# MailCatcher
+
+Catches mail and serves it through a dream.
+
+MailCatcher runs a super simple SMTP server which catches any message sent to it to display in a web interface. Run mailcatcher, set your favourite app to deliver to smtp://127.0.0.1:1025 instead of your default SMTP server, then check out http://127.0.0.1:1080 to see the mail that's arrived so far.
+
+![MailCatcher screenshot](https://cloud.githubusercontent.com/assets/14028/14093249/4100f904-f598-11e5-936b-e6a396f18e39.png)
+
+## Features
+
+* Catches all mail and stores it for display.
+* Shows HTML, Plain Text and Source version of messages, as applicable.
+* Rewrites HTML enabling display of embedded, inline images/etc and opens links in a new window.
+* Lists attachments and allows separate downloading of parts.
+* Download original email to view in your native mail client(s).
+* Command line options to override the default SMTP/HTTP IP and port settings.
+* Mail appears instantly if your browser supports [WebSockets][websockets], otherwise updates every thirty seconds.
+* Runs as a daemon in the background, optionally in foreground.
+* Sendmail-analogue command, `catchmail`, makes using mailcatcher from PHP a lot easier.
+* Keyboard navigation between messages
+
+## How
+
+1. `gem install mailcatcher`
+2. `mailcatcher`
+3. Go to http://127.0.0.1:1080/
+4. Send mail through smtp://127.0.0.1:1025
+
+### Command Line Options
+
+Use `mailcatcher --help` to see the command line options.
+
+```
+Usage: mailcatcher [options]
+
+MailCatcher v0.8.0
+
+        --ip IP                      Set the ip address of both servers
+        --smtp-ip IP                 Set the ip address of the smtp server
+        --smtp-port PORT             Set the port of the smtp server
+        --http-ip IP                 Set the ip address of the http server
+        --http-port PORT             Set the port address of the http server
+        --messages-limit COUNT       Only keep up to COUNT most recent messages
+        --http-path PATH             Add a prefix to all HTTP paths
+        --no-quit                    Don't allow quitting the process
+    -f, --foreground                 Run in the foreground
+    -b, --browse                     Open web browser
+    -v, --verbose                    Be more verbose
+    -h, --help                       Display this help information
+        --version                    Display the current version
+```
+
+### Upgrading
+
+Upgrading works the same as installation:
+
+```
+gem install mailcatcher
+```
+
+### Ruby
+
+If you have trouble with the setup commands, make sure you have [Ruby installed](https://www.ruby-lang.org/en/documentation/installation/):
+
+```
+ruby -v
+gem environment
+```
+
+You might need to install build tools for some of the gem dependencies. On Debian or Ubuntu, `apt install build-essential`. On macOS, `xcode-select --install`.
+
+If you encounter issues installing [thin](https://rubygems.org/gems/thin), try:
+
+```
+gem install thin -v 1.5.1 -- --with-cflags="-Wno-error=implicit-function-declaration"
+```
+
+### Bundler
+
+Please don't put mailcatcher into your Gemfile. It will conflict with your application's gems at some point.
+
+Instead, pop a note in your README stating you use mailcatcher, and to run `gem install mailcatcher` then `mailcatcher` to get started.
+
+### RVM
+
+Under RVM your mailcatcher command may only be available under the ruby you install mailcatcher into. To prevent this, and to prevent gem conflicts, install mailcatcher into a dedicated gemset with a wrapper script:
+
+    rvm default@mailcatcher --create do gem install mailcatcher
+    ln -s "$(rvm default@mailcatcher do rvm wrapper show mailcatcher)" "$rvm_bin_path/"
+
+### Rails
+
+To set up your rails app, I recommend adding this to your `environments/development.rb`:
+
+    config.action_mailer.delivery_method = :smtp
+    config.action_mailer.smtp_settings = { :address => '127.0.0.1', :port => 1025 }
+    config.action_mailer.raise_delivery_errors = false
+
+### PHP
+
+For projects using PHP, or PHP frameworks and application platforms like Drupal, you can set [PHP's mail configuration](https://www.php.net/manual/en/mail.configuration.php) in your [php.ini](https://www.php.net/manual/en/configuration.file.php) to send via MailCatcher with:
+
+    sendmail_path = /usr/bin/env catchmail -f some@from.address
+
+You can do this in your [Apache configuration](https://www.php.net/manual/en/configuration.changes.php) like so:
+
+    php_admin_value sendmail_path "/usr/bin/env catchmail -f some@from.address"
+
+If you've installed via RVM this probably won't work unless you've manually added your RVM bin paths to your system environment's PATH. In that case, run `which catchmail` and put that path into the `sendmail_path` directive above instead of `/usr/bin/env catchmail`.
+
+If starting `mailcatcher` on alternative SMTP IP and/or port with parameters like `--smtp-ip 192.168.0.1 --smtp-port 10025`, add the same parameters to your `catchmail` command:
+
+    sendmail_path = /usr/bin/env catchmail --smtp-ip 192.160.0.1 --smtp-port 10025 -f some@from.address
+
+### Django
+
+For use in Django, add the following configuration to your projects' settings.py
+
+```python
+if DEBUG:
+    EMAIL_HOST = '127.0.0.1'
+    EMAIL_HOST_USER = ''
+    EMAIL_HOST_PASSWORD = ''
+    EMAIL_PORT = 1025
+    EMAIL_USE_TLS = False
+```
+
+### Docker
+
+There is a Docker image available [on Docker Hub](https://hub.docker.com/r/sj26/mailcatcher):
+
+```
+$ docker run -p 1080 -p 1025 sj26/mailcatcher
+Unable to find image 'sj26/mailcatcher:latest' locally
+latest: Pulling from sj26/mailcatcher
+8c6d1654570f: Already exists
+f5649d186f41: Already exists
+b850834ea1df: Already exists
+d6ac1a07fd46: Pull complete
+b609298bc3c9: Pull complete
+ab05825ece51: Pull complete
+Digest: sha256:b17c45de08a0a82b012d90d4bd048620952c475f5655c61eef373318de6c0855
+Status: Downloaded newer image for sj26/mailcatcher:latest
+Starting MailCatcher v0.9.0
+==> smtp://0.0.0.0:1025
+==> http://0.0.0.0:1080
+```
+
+How those ports appear and can be accessed may vary based on your Docker configuration. For example, your may need to use `http://127.0.0.1:1080` etc instead of the listed address. But MailCatcher will run and listen to those ports on all IPs it can from within the Docker container.
+
+### API
+
+A fairly RESTful URL schema means you can download a list of messages in JSON from `/messages`, each message's metadata with `/messages/:id.json`, and then the pertinent parts with `/messages/:id.html` and `/messages/:id.plain` for the default HTML and plain text version, `/messages/:id/parts/:cid` for individual attachments by CID, or the whole message with `/messages/:id.source`.
+
+## Caveats
+
+* Mail processing is fairly basic but easily modified. If something doesn't work for you, fork and fix it or [file an issue][mailcatcher-issues] and let me know. Include the whole message you're having problems with.
+* Encodings are difficult. MailCatcher does not completely support utf-8 straight over the wire, you must use a mail library which encodes things properly based on SMTP server capabilities.
+
+## Thanks
+
+MailCatcher is just a mishmash of other people's hard work. Thank you so much to the people who have built the wonderful guts on which this project relies.
+
+## Donations
+
+I work on MailCatcher mostly in my own spare time. If you've found Mailcatcher useful and would like to help feed me and fund continued development and new features, please [donate via PayPal][donate]. If you'd like a specific feature added to MailCatcher and are willing to pay for it, please [email me](mailto:sj26@sj26.com).
+
+## License
+
+Copyright © 2010-2019 Samuel Cochran (sj26@sj26.com). Released under the MIT License, see [LICENSE][license] for details.
+
+  [donate]: https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=522WUPLRWUSKE
+  [license]: https://github.com/sj26/mailcatcher/blob/master/LICENSE
+  [mailcatcher-github]: https://github.com/sj26/mailcatcher
+  [mailcatcher-issues]: https://github.com/sj26/mailcatcher/issues
+  [websockets]: https://tools.ietf.org/html/rfc6455

data/bin/catchmail

@@ -0,0 +1,72 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+begin
+  require 'mail'
+rescue LoadError
+  require 'rubygems'
+  require 'mail'
+end
+
+require 'optparse'
+
+options = {:smtp_ip => '127.0.0.1', :smtp_port => 1025}
+
+OptionParser.new do |parser|
+  parser.banner = <<-BANNER.gsub /^ +/, ""
+    Usage: catchmail [options] [recipient ...]
+    sendmail-like interface to forward mail to MailCatcher.
+  BANNER
+
+  parser.on('--ip IP') do |ip|
+    options[:smtp_ip] = ip
+  end
+
+  parser.on('--smtp-ip IP', 'Set the ip address of the smtp server') do |ip|
+    options[:smtp_ip] = ip
+  end
+
+  parser.on('--smtp-port PORT', Integer, 'Set the port of the smtp server') do |port|
+    options[:smtp_port] = port
+  end
+
+  parser.on('-f FROM', 'Set the sending address') do |from|
+    options[:from] = from
+  end
+
+  parser.on('-oi', 'Ignored option -oi') do |ignored|
+  end
+  parser.on('-t', 'Ignored option -t') do |ignored|
+  end
+  parser.on('-q', 'Ignored option -q') do |ignored|
+  end
+
+  parser.on('-x', '--no-exit', 'Can\'t exit from the application') do
+    options[:no_exit] = true
+  end
+
+  parser.on('-h', '--help', 'Display this help information') do
+    puts parser
+    exit!
+  end
+end.parse!
+
+Mail.defaults do
+  delivery_method :smtp,
+    :address => options[:smtp_ip],
+    :port => options[:smtp_port]
+end
+
+message = Mail.new($stdin.read)
+
+message.return_path = options[:from] if options[:from]
+
+ARGV.each do |recipient|
+  if message.to.nil?
+    message.to = recipient
+  else
+    message.to << recipient
+  end
+end
+
+message.deliver

data/bin/mailcatcher

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'mail_catcher'
+
+MailCatcher.run!

data/lib/mail_catcher/bus.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require "eventmachine"
+
+module MailCatcher
+  Bus = EventMachine::Channel.new
+end

data/lib/mail_catcher/mail.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "eventmachine"
+require "json"
+require "mail"
+require "sqlite3"
+
+module MailCatcher::Mail extend self
+  def db
+    @__db ||= begin
+      SQLite3::Database.new("/srv/mailcatcher.db", :type_translation => true).tap do |db|
+        db.execute(<<-SQL)
+          CREATE TABLE message (
+            id INTEGER PRIMARY KEY ASC,
+            sender TEXT,
+            recipients TEXT,
+            subject TEXT,
+            source BLOB,
+            size TEXT,
+            type TEXT,
+            created_at DATETIME DEFAULT CURRENT_DATETIME
+          )
+        SQL
+        db.execute(<<-SQL)
+          CREATE TABLE message_part (
+            id INTEGER PRIMARY KEY ASC,
+            message_id INTEGER NOT NULL,
+            cid TEXT,
+            type TEXT,
+            is_attachment INTEGER,
+            filename TEXT,
+            charset TEXT,
+            body BLOB,
+            size INTEGER,
+            created_at DATETIME DEFAULT CURRENT_DATETIME,
+            FOREIGN KEY (message_id) REFERENCES message (id) ON DELETE CASCADE
+          )
+        SQL
+        db.execute("PRAGMA foreign_keys = ON")
+      end
+    end
+  end
+
+  def add_message(message)
+    @add_message_query ||= db.prepare("INSERT INTO message (sender, recipients, subject, source, type, size, created_at) VALUES (?, ?, ?, ?, ?, ?, datetime('now'))")
+
+    mail = Mail.new(message[:source])
+    @add_message_query.execute(message[:sender], JSON.generate(message[:recipients]), mail.subject, message[:source], mail.mime_type || "text/plain", message[:source].length)
+    message_id = db.last_insert_row_id
+    parts = mail.all_parts
+    parts = [mail] if parts.empty?
+    parts.each do |part|
+      body = part.body.to_s
+      # Only parts have CIDs, not mail
+      cid = part.cid if part.respond_to? :cid
+      add_message_part(message_id, cid, part.mime_type || "text/plain", part.attachment? ? 1 : 0, part.filename, part.charset, body, body.length)
+    end
+
+    EventMachine.next_tick do
+      message = MailCatcher::Mail.message message_id
+      MailCatcher::Bus.push(type: "add", message: message)
+    end
+  end
+
+  def add_message_part(*args)
+    @add_message_part_query ||= db.prepare "INSERT INTO message_part (message_id, cid, type, is_attachment, filename, charset, body, size, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, datetime('now'))"
+    @add_message_part_query.execute(*args)
+  end
+
+  def latest_created_at
+    @latest_created_at_query ||= db.prepare "SELECT created_at FROM message ORDER BY created_at DESC LIMIT 1"
+    @latest_created_at_query.execute.next
+  end
+
+  def messages
+    @messages_query ||= db.prepare "SELECT id, sender, recipients, subject, size, created_at FROM message ORDER BY created_at, id ASC"
+    @messages_query.execute.map do |row|
+      Hash[row.fields.zip(row)].tap do |message|
+        message["recipients"] &&= JSON.parse(message["recipients"])
+      end
+    end
+  end
+
+  def message(id)
+    @message_query ||= db.prepare "SELECT id, sender, recipients, subject, size, type, created_at FROM message WHERE id = ? LIMIT 1"
+    row = @message_query.execute(id).next
+    row && Hash[row.fields.zip(row)].tap do |message|
+      message["recipients"] &&= JSON.parse(message["recipients"])
+    end
+  end
+
+  def message_source(id)
+    @message_source_query ||= db.prepare "SELECT source FROM message WHERE id = ? LIMIT 1"
+    row = @message_source_query.execute(id).next
+    row && row.first
+  end
+
+  def message_has_html?(id)
+    @message_has_html_query ||= db.prepare "SELECT 1 FROM message_part WHERE message_id = ? AND is_attachment = 0 AND type IN ('application/xhtml+xml', 'text/html') LIMIT 1"
+    (!!@message_has_html_query.execute(id).next) || ["text/html", "application/xhtml+xml"].include?(message(id)["type"])
+  end
+
+  def message_has_plain?(id)
+    @message_has_plain_query ||= db.prepare "SELECT 1 FROM message_part WHERE message_id = ? AND is_attachment = 0 AND type = 'text/plain' LIMIT 1"
+    (!!@message_has_plain_query.execute(id).next) || message(id)["type"] == "text/plain"
+  end
+
+  def message_parts(id)
+    @message_parts_query ||= db.prepare "SELECT cid, type, filename, size FROM message_part WHERE message_id = ? ORDER BY filename ASC"
+    @message_parts_query.execute(id).map do |row|
+      Hash[row.fields.zip(row)]
+    end
+  end
+
+  def message_attachments(id)
+    @message_parts_query ||= db.prepare "SELECT cid, type, filename, size FROM message_part WHERE message_id = ? AND is_attachment = 1 ORDER BY filename ASC"
+    @message_parts_query.execute(id).map do |row|
+      Hash[row.fields.zip(row)]
+    end
+  end
+
+  def message_part(message_id, part_id)
+    @message_part_query ||= db.prepare "SELECT * FROM message_part WHERE message_id = ? AND id = ? LIMIT 1"
+    row = @message_part_query.execute(message_id, part_id).next
+    row && Hash[row.fields.zip(row)]
+  end
+
+  def message_part_type(message_id, part_type)
+    @message_part_type_query ||= db.prepare "SELECT * FROM message_part WHERE message_id = ? AND type = ? AND is_attachment = 0 LIMIT 1"
+    row = @message_part_type_query.execute(message_id, part_type).next
+    row && Hash[row.fields.zip(row)]
+  end
+
+  def message_part_html(message_id)
+    part = message_part_type(message_id, "text/html")
+    part ||= message_part_type(message_id, "application/xhtml+xml")
+    part ||= begin
+      message = message(message_id)
+      message if message and ["text/html", "application/xhtml+xml"].include? message["type"]
+    end
+  end
+
+  def message_part_plain(message_id)
+    message_part_type message_id, "text/plain"
+  end
+
+  def message_part_cid(message_id, cid)
+    @message_part_cid_query ||= db.prepare "SELECT * FROM message_part WHERE message_id = ?"
+    @message_part_cid_query.execute(message_id).map do |row|
+      Hash[row.fields.zip(row)]
+    end.find do |part|
+      part["cid"] == cid
+    end
+  end
+
+  def delete!
+    @delete_all_messages_query ||= db.prepare "DELETE FROM message"
+    @delete_all_messages_query.execute
+
+    EventMachine.next_tick do
+      MailCatcher::Bus.push(type: "clear")
+    end
+  end
+
+  def delete_message!(message_id)
+    @delete_messages_query ||= db.prepare "DELETE FROM message WHERE id = ?"
+    @delete_messages_query.execute(message_id)
+
+    EventMachine.next_tick do
+      MailCatcher::Bus.push(type: "remove", id: message_id)
+    end
+  end
+
+  def delete_older_messages!(count = MailCatcher.options[:messages_limit])
+    return if count.nil?
+    @older_messages_query ||= db.prepare "SELECT id FROM message WHERE id NOT IN (SELECT id FROM message ORDER BY created_at DESC LIMIT ?)"
+    @older_messages_query.execute(count).map do |row|
+      Hash[row.fields.zip(row)]
+    end.each do |message|
+      delete_message!(message["id"])
+    end
+  end
+end

data/lib/mail_catcher/smtp.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "eventmachine"
+
+require "mail_catcher/mail"
+
+class MailCatcher::Smtp < EventMachine::Protocols::SmtpServer
+  # We override EM's mail from processing to allow multiple mail-from commands
+  # per [RFC 2821](https://tools.ietf.org/html/rfc2821#section-4.1.1.2)
+  def process_mail_from sender
+    if @state.include? :mail_from
+      @state -= [:mail_from, :rcpt, :data]
+
+      receive_reset
+    end
+
+    super
+  end
+
+  def current_message
+    @current_message ||= {}
+  end
+
+  def receive_reset
+    @current_message = nil
+
+    true
+  end
+
+  def receive_sender(sender)
+    # EventMachine SMTP advertises size extensions [https://tools.ietf.org/html/rfc1870]
+    # so strip potential " SIZE=..." suffixes from senders
+    sender = $` if sender =~ / SIZE=\d+\z/
+
+    current_message[:sender] = sender
+
+    true
+  end
+
+  def receive_recipient(recipient)
+    current_message[:recipients] ||= []
+    current_message[:recipients] << recipient
+
+    true
+  end
+
+  def receive_data_chunk(lines)
+    current_message[:source] ||= +""
+
+    lines.each do |line|
+      current_message[:source] << line << "\r\n"
+    end
+
+    true
+  end
+
+  def receive_message
+    MailCatcher::Mail.add_message current_message
+    MailCatcher::Mail.delete_older_messages!
+    puts "==> SMTP: Received message from '#{current_message[:sender]}' (#{current_message[:source].length} bytes)"
+    true
+  rescue => exception
+    MailCatcher.log_exception("Error receiving message", @current_message, exception)
+    false
+  ensure
+    @current_message = nil
+  end
+end

data/lib/mail_catcher/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MailCatcher
+  VERSION = "0.10.0"
+end