mail_grabber 1.0.0.rc1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d564e5c8027b8dd25676e1076cddefda9c055cf694df0fb8824ef836c0c8c31d
+  data.tar.gz: 4599ee2a8e4491b26df2d44005eeb11594993b889bdc3a1e277c284b6a8422bf
+SHA512:
+  metadata.gz: 5e58191d8045ef116faffeb4574f5d875e0cf0c9a1387354d151226981d318752bc9ba675e0d8ade11629f45f69ac247f65d6bc71724f4655b00612d199c52e9
+  data.tar.gz: 3b07b4809a2d9326ff95790f02c0d2ef89252f688e9d7968784aae2d37a69bffc431c74a5495f187faafe1f5b5d3538d29f476e0cda58b95bcaf816d39b4a693

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Change log
+
+## 1.0.0.rc1 (2021-03-20)
+
+* Implement MailGrabber methods and functionality. See [README.md](https://github.com/MailToolbox/mail_grabber/blob/main/README.md)

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Norbert Szivós
+
+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,66 @@
+# M<img src="https://raw.githubusercontent.com/MailToolbox/mail_grabber/main/images/mail_grabber515x500.png" height="22" />ilGrabber
+
+[![Gem Version](https://badge.fury.io/rb/mail_grabber.svg)](https://badge.fury.io/rb/mail_grabber)
+[![MIT license](https://img.shields.io/badge/license-MIT-brightgreen)](https://github.com/MailToolbox/mail_grabber/blob/main/LICENSE.txt)
+[![Ruby Style Guide](https://img.shields.io/badge/code_style-rubocop-brightgreen.svg)](https://github.com/rubocop-hq/rubocop)
+[![Build Status](https://travis-ci.com/MailToolbox/mail_grabber.svg?branch=main)](https://travis-ci.com/MailToolbox/mail_grabber)
+[![Maintainability](https://api.codeclimate.com/v1/badges/97deed5c1fbd003ca810/maintainability)](https://codeclimate.com/github/MailToolbox/mail_grabber/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/97deed5c1fbd003ca810/test_coverage)](https://codeclimate.com/github/MailToolbox/mail_grabber/test_coverage)
+
+**MailGrabber** is yet another solution to inspect sent emails.
+
+It has two part:
+- delivery method to grab emails and store into a database
+- simple rack web interface to check those emails
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'mail_grabber'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install mail_grabber
+
+## Usage
+
+- [How to use MailGrabber in a Ruby script or IRB console](https://github.com/MailToolbox/mail_grabber/blob/main/docs/usage_in_script_or_console.md)
+- [How to use MailGrabber in Ruby on Rails](https://github.com/MailToolbox/mail_grabber/blob/main/docs/usage_in_ruby_on_rails.md)
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+To release a new version:
+
+- Update [CHANGELOG.md](https://github.com/MailToolbox/mail_grabber/blob/main/CHANGELOG.md)
+- Update the version number in `version.rb` manually or use `gem-release` gem and run `gem bump -v major|minor|patch|rc|beta`.
+- Build gem with `bundle exec rake build`.
+- Run `bundle install` to update gemfiles and commit the changes.
+- Run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome. Please read [CONTRIBUTING.md](https://github.com/MailToolbox/mail_grabber/blob/main/CONTRIBUTING.md) if you would like to contribute to this project.
+
+## Inspiration
+
+- [MailCatcher](https://github.com/sj26/mailcatcher)
+- [letter_opener_web](https://github.com/fgrehm/letter_opener_web)
+- [Rack](https://github.com/rack/rack)
+- [Rack::Router](https://github.com/pjb3/rack-router)
+- [Sidekiq](https://github.com/mperham/sidekiq)
+- and other solutions regarding in this topic
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://github.com/MailToolbox/mail_grabber/blob/main/LICENSE.txt).

data/lib/mail_grabber.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'mail_grabber/error'
+require 'mail_grabber/database_helper'
+require 'mail_grabber/delivery_method'
+# If we are using this gem outside of Rails then do not load this code.
+require 'mail_grabber/railtie' if defined?(Rails)
+require 'mail_grabber/version'

data/lib/mail_grabber/database_helper.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'sqlite3'
+
+require 'mail_grabber/database_queries'
+
+module MailGrabber
+  module DatabaseHelper
+    include DatabaseQueries
+
+    DATABASE = {
+      folder: 'tmp',
+      filename: 'mail_grabber.sqlite3',
+      params: {
+        type_translation: true,
+        results_as_hash: true
+      }
+    }.freeze
+
+    # Create connection to the SQLite3 database. Use foreign_keys pragmas that
+    # we can use DELETE CASCADE option. It accepts block to execute queries.
+    # If something goes wrong then it raise database helper error.
+    # Also ensure to close the database (important to close database if we are
+    # don't want to see database busy errors).
+    def connection
+      database = open_database
+      database.foreign_keys = 'ON'
+
+      yield database
+    rescue SQLite3::Exception => e
+      raise Error::DatabaseHelperError, e
+    ensure
+      database&.close
+    end
+
+    # Create connection and execute a query.
+    #
+    # @param [String] query which query we would like to execute
+    # @param [Array] args any arguments which we will use in the query
+    def connection_execute(query, *args)
+      connection { |db| db.execute(query, *args) }
+    end
+
+    # Create connection and execute many queries in transaction. It accepts
+    # block to execute queries. If something goes wrong it rolls back the
+    # changes and raise database helper error.
+    def connection_execute_transaction
+      connection do |db|
+        db.transaction
+
+        yield db
+
+        db.commit
+      rescue SQLite3::Exception => e
+        db.rollback
+
+        raise Error::DatabaseHelperError, e
+      end
+    end
+
+    # Helper method to delete all messages.
+    def delete_all_messages
+      connection_execute('DELETE FROM mail')
+    end
+
+    # Helper method to delete a message.
+    #
+    # @param [String/Integer] id the identifier of the message
+    def delete_message_by(id)
+      connection_execute('DELETE FROM mail WHERE id = ?', id.to_i)
+    end
+
+    # Helper method to get all messages.
+    def select_all_messages
+      connection_execute('SELECT * FROM mail ORDER BY id DESC, created_at DESC')
+    end
+
+    # Helper method to get a message.
+    #
+    # @param [String/Integer] id the identifier of the message
+    def select_message_by(id)
+      connection_execute('SELECT * FROM mail WHERE id = ?', id.to_i).first
+    end
+
+    # Helper method to get a message part.
+    #
+    # @param [String/Integer] id the identifier of the message part
+    def select_message_parts_by(id)
+      connection_execute('SELECT * FROM mail_part WHERE mail_id = ?', id.to_i)
+    end
+
+    # Helper method to get a specific number of messages. We can specify which
+    # part of the table we need and how many messages want to see.
+    #
+    # @param [String/Integer] page which part of the table want to see
+    # @param [String/Integer] per_page how many messages gives back
+    def select_messages_by(page, per_page)
+      page = page.to_i
+      per_page = per_page.to_i
+
+      connection_execute(
+        select_messages_with_pagination_query,
+        per_page * (page - 1),
+        per_page
+      )
+    end
+
+    # Helper method to store a message in the database.
+    #
+    # @param [Mail::Message] message which we would like to store
+    def store_mail(message)
+      connection_execute_transaction do |db|
+        insert_into_mail(db, message)
+
+        insert_into_mail_part(db, message)
+      end
+    end
+
+    private
+
+    # Check that the given Mail::Part is an attachment or not.
+    #
+    # @param [Mail::Part] object
+    #
+    # @return [Integer] 1 if it is an attachment, else 0
+    def attachment?(object)
+      object.attachment? ? 1 : 0
+    end
+
+    # Convert the given message or body to utf8 string. Needs this that we can
+    # send it as JSON.
+    #
+    # @param [Mail::Message/Mail::Body] object
+    #
+    # @return [String] which we can store in the database and send as JSON
+    def convert_to_utf8_string(object)
+      object.to_s.force_encoding('UTF-8')
+    end
+
+    # Encode the given decoded body with base64 encoding if Mail::Part is an
+    # attachment.
+    #
+    # @param [Mail::Part] object
+    # @param [String] string the decoded body of the Mail::Part
+    #
+    # @return [String] with the encoded or the original body
+    def encode_if_attachment(object, string)
+      object.attachment? ? Base64.encode64(string) : string
+    end
+
+    # Extract cid value from the Mail::Part.
+    #
+    # @param [Mail::Part] object
+    #
+    # @return [String] the cid value
+    def extract_cid(object)
+      object.cid if object.respond_to?(:cid)
+    end
+
+    # Extract all parts from the Mail::Message object. If it is not multipart
+    # then it returns back with original object in an Array.
+    #
+    # @param [Mail::Message] message
+    #
+    # @return [Array] with all parts of the message or an Array with the message
+    def extract_mail_parts(message)
+      message.multipart? ? message.all_parts : [message]
+    end
+
+    # Extract MIME type of the Mail::Part object. If it is nil then it returns
+    # with text/plain value.
+    #
+    # @param [Mail::Part] object
+    #
+    # @return [String] with MIME type of the part
+    def extract_mime_type(object)
+      object.mime_type || 'text/plain'
+    end
+
+    # Check that the given Mail::Part is an inline attachment or not.
+    #
+    # @param [Mail::Part] object
+    #
+    # @return [Integer] 1 if it is an inline attachment, else 0
+    def inline?(object)
+      object.respond_to?(:inline?) && object.inline? ? 1 : 0
+    end
+
+    # Store Mail::Message in the database.
+    #
+    # @param [SQLite::Database] db
+    # @param [Mail::Message] message
+    def insert_into_mail(db, message)
+      db.execute(
+        insert_into_mail_query,
+        message.subject,
+        message.from&.join(', '),
+        message.to&.join(', '),
+        message.cc&.join(', '),
+        message.bcc&.join(', '),
+        convert_to_utf8_string(message)
+      )
+    end
+
+    # Store Mail::Part in the database.
+    #
+    # @param [SQLite::Database] db
+    # @param [Mail::Message] message
+    def insert_into_mail_part(db, message)
+      mail_id = db.last_insert_row_id
+
+      extract_mail_parts(message).each do |part|
+        body = part.decoded
+
+        db.execute(
+          insert_into_mail_part_query,
+          mail_id,
+          extract_cid(part),
+          extract_mime_type(part),
+          attachment?(part),
+          inline?(part),
+          part.filename,
+          part.charset,
+          encode_if_attachment(part, body),
+          body.length
+        )
+      end
+    end
+
+    # Open a database connection with the database. Also it checks that the
+    # database is exist or not. If it does not exist then it creates a new one.
+    #
+    # @return [SQLite3::Database] a database object
+    def open_database
+      db_location = "#{DATABASE[:folder]}/#{DATABASE[:filename]}"
+
+      if File.exist?(db_location)
+        SQLite3::Database.new(db_location, **DATABASE[:params])
+      else
+        Dir.mkdir(DATABASE[:folder]) unless Dir.exist?(DATABASE[:folder])
+
+        SQLite3::Database.new(db_location, **DATABASE[:params]).tap do |db|
+          create_mail_table(db)
+          create_mail_part_table(db)
+        end
+      end
+    end
+  end
+end

data/lib/mail_grabber/database_queries.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module MailGrabber
+  module DatabaseQueries
+    # Create mail table if it is not exist.
+    #
+    # @param [SQLite3::Database] db to execute create table query
+    def create_mail_table(db)
+      db.execute(<<-SQL)
+        CREATE TABLE IF NOT EXISTS mail (
+          id INTEGER PRIMARY KEY,
+          subject TEXT,
+          senders TEXT,
+          recipients TEXT,
+          carbon_copy TEXT,
+          blind_carbon_copy TEXT,
+          raw BLOB,
+          created_at DATETIME DEFAULT CURRENT_DATETIME
+        )
+      SQL
+    end
+
+    # Create mail part table if it is not exist.
+    #
+    # @param [SQLite3::Database] db to execute create table query
+    def create_mail_part_table(db)
+      db.execute(<<-SQL)
+        CREATE TABLE IF NOT EXISTS mail_part (
+          id INTEGER PRIMARY KEY,
+          mail_id INTEGER NOT NULL,
+          cid TEXT,
+          mime_type TEXT,
+          is_attachment INTEGER,
+          is_inline INTEGER,
+          filename TEXT,
+          charset TEXT,
+          body BLOB,
+          size INTEGER,
+          created_at DATETIME DEFAULT CURRENT_DATETIME,
+          FOREIGN KEY (mail_id) REFERENCES mail(id) ON DELETE CASCADE
+        )
+      SQL
+    end
+
+    # Insert mail query.
+    #
+    # @return [Srting] with the insert mail query
+    def insert_into_mail_query
+      <<-SQL
+        INSERT INTO mail (
+          subject,
+          senders,
+          recipients,
+          carbon_copy,
+          blind_carbon_copy,
+          raw,
+          created_at
+        )
+        VALUES (?, ?, ?, ?, ?, ?, datetime('now'))
+      SQL
+    end
+
+    # Insert mail part query.
+    #
+    # @return [Srting] with the insert mail part query
+    def insert_into_mail_part_query
+      <<-SQL
+        INSERT INTO mail_part (
+          mail_id,
+          cid,
+          mime_type,
+          is_attachment,
+          is_inline,
+          filename,
+          charset,
+          body,
+          size,
+          created_at
+        )
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, datetime('now'))
+      SQL
+    end
+
+    # Select messages with pagination query.
+    #
+    # @return [Srting] with the select messages query
+    def select_messages_with_pagination_query
+      <<-SQL
+        SELECT id, subject, senders, created_at
+        FROM mail
+        WHERE id NOT IN (
+          SELECT id
+          FROM mail
+          ORDER BY id DESC, created_at DESC
+          LIMIT ?
+        )
+        ORDER BY id DESC, created_at DESC
+        LIMIT ?
+      SQL
+    end
+  end
+end