truemail 1.7.0 → 1.9.2

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2019 Vladislav Trotsenko
+Copyright (c) 2019-2020 Vladislav Trotsenko
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,9 +1,11 @@
-# <img src='https://repository-images.githubusercontent.com/173723932/6dffee00-e88e-11e9-94b6-c97aacc0df00' height='250' alt='Truemail - configurable framework agnostic plain Ruby email validator' />
+![Truemail - configurable framework agnostic plain Ruby email validator](https://truemail-rb.org/assets/images/truemail_logo.png)
 
 [![Maintainability](https://api.codeclimate.com/v1/badges/657aa241399927dcd2e2/maintainability)](https://codeclimate.com/github/rubygarage/truemail/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/657aa241399927dcd2e2/test_coverage)](https://codeclimate.com/github/rubygarage/truemail/test_coverage) [![CircleCI](https://circleci.com/gh/rubygarage/truemail/tree/master.svg?style=svg)](https://circleci.com/gh/rubygarage/truemail/tree/master) [![Gem Version](https://badge.fury.io/rb/truemail.svg)](https://badge.fury.io/rb/truemail) [![Downloads](https://img.shields.io/gem/dt/truemail.svg?colorA=004d99&colorB=0073e6)](https://rubygems.org/gems/truemail) [![Gitter](https://badges.gitter.im/truemail-rb/community.svg)](https://gitter.im/truemail-rb/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v1.4%20adopted-ff69b4.svg)](CODE_OF_CONDUCT.md)
 
 Configurable framework agnostic plain Ruby email validator. Verify email via Regex, DNS and SMTP. Be sure that email address valid and exists.
 
+> Actual and maintainable documentation :books: for developers is living [here](https://truemail-rb.org/truemail-gem).
+
 ## Table of Contents
 
 - [Synopsis](#synopsis)
@@ -32,11 +34,16 @@ Configurable framework agnostic plain Ruby email validator. Verify email via Reg
     - [SMTP validation](#smtp-validation)
       - [SMTP safe check disabled](#smtp-safe-check-disabled)
       - [SMTP safe check enabled](#smtp-safe-check-enabled)
-  - [Event logger](#event-logger)
-    - [Available tracking events](#available-tracking-events)
-  - [JSON serializer](#json-serializer)
   - [Host audit features](#host-audit-features)
+    - [IP audit](#ip-audit)
+    - [DNS audit](#dns-audit)
     - [PTR audit](#ptr-audit)
+    - [Example of using](#example-of-using)
+  - [Event logger](#event-logger)
+    - [Available tracking events](#available-tracking-events)
+  - [JSON serializers](#json-serializers)
+    - [Auditor JSON serializer](#auditor-json-serializer)
+    - [Validator JSON serializer](#validator-json-serializer)
   - [Truemail helpers](#truemail-helpers)
     - [.valid?](#valid)
     - [#as_json](#as_json)
@@ -48,11 +55,10 @@ Configurable framework agnostic plain Ruby email validator. Verify email via Reg
 - [Credits](#credits)
 - [Versioning](#versioning)
 - [Changelog](CHANGELOG.md)
-- [Wiki](https://github.com/rubygarage/truemail/wiki)
 
 ## Synopsis
 
-Email validation is a tricky thing. There are a number of different ways to validate an email address and all mechanisms must conform with the best practices and provide proper validation. You can get more information about email validation techniques in our [blog](https://rubygarage.org/blog/how-to-validate-emails). The Truemail gem helps you validate emails via regex pattern, presence of DNS records, and real existence of email account on a current email server.
+Email validation is a tricky thing. There are a number of different ways to validate an email address and all mechanisms must conform with the best practices and provide proper validation. The Truemail gem helps you validate emails via regex pattern, presence of DNS records, and real existence of email account on a current email server.
 
 **Syntax Checking**: Checks the email addresses via regex pattern.
 
@@ -70,7 +76,8 @@ Also Truemail gem allows performing an audit of the host in which runs.
 - Whitelist/blacklist validation layers
 - Simple SMTP debugger
 - Event logger
-- JSON serializer
+- Host auditor tools (helps to detect common host problems interfering to proper email verification)
+- JSON serializers
 
 ## Requirements
 
@@ -892,76 +899,33 @@ Truemail.validate('email@example.com')
     @validation_type=:smtp>
 ```
 
-### Event logger
-
-Truemail gem allows to output tracking events to stdout/file or both of these. Please note, at least one of the outputs must exist. Tracking event by default is `:error`
-
-```ruby
-Truemail.configure do |config|
-  config.logger = { tracking_event: :all, stdout: true, log_absolute_path: '/home/app/log/truemail.log' }
-end
-```
-
-#### Available tracking events
-
-- `:all`, all detected events including success validation cases
-- `:unrecognized_error`, unrecognized errors only (when `smtp_safe_check = true` and SMTP server does not return an exact answer that the email does not exist)
-- `:recognized_error`, recognized errors only
-- `:error`, recognized and unrecognized errors only
+### Host audit features
 
-### JSON serializer
+Truemail gem allows performing an audit of the host in which runs. It will help to detect common host problems interfering to proper email verification.
 
-Truemail has built in JSON serializer for `Truemail::Validator` instance, so you can represent your email validation result as json.
+#### IP audit
 
-```ruby
-Truemail::Log::Serializer::Json.call(Truemail.validate('nonexistent_email@bestweb.com.ua'))
-
-=>
-# Serialized Truemail::Validator instance
-{
-  "date": "2019-10-28 10:15:51 +0200",
-  "email": "nonexistent_email@bestweb.com.ua",
-  "validation_type": "smtp",
-  "success": false,
-  "errors": {
-    "smtp": "smtp error"
-  },
-  "smtp_debug": [
-    {
-      "mail_host": "213.180.193.89",
-      "port_opened": true,
-      "connection": true,
-      "errors": {
-        "rcptto": "550 5.7.1 No such user!\n"
-      }
-    }
-  ],
-  "configuration": {
-    "validation_type_by_domain": null,
-    "whitelist_validation": false,
-    "whitelisted_domains": null,
-    "blacklisted_domains": null,
-    "smtp_safe_check": false,
-    "email_pattern": "default gem value",
-    "smtp_error_body_pattern": "default gem value"
-  }
-}
-```
+Checks is current Truemail host has proper internet connection and detects current host ip address.
 
-### Host audit features
+#### DNS audit
 
-Truemail gem allows performing an audit of the host in which runs. Only PTR record audit performs for today.
+Checks is verifier domain refer to current Truemail host IP address.
 
 #### PTR audit
 
 So what is a PTR record? A PTR record, or pointer record, enables someone to perform a reverse DNS lookup. This allows them to determine your domain name based on your IP address. Because generic domain names without a PTR are often associated with spammers, incoming mail servers identify email from hosts without PTR records as spam and you can't verify yours emails qualitatively.
 
+Checks is PTR record exists for your Truemail host ip address exists and refers to current verifier domain.
+
+#### Example of using
+
 ```ruby
 Truemail.host_audit
 # Everything is good
 => #<Truemail::Auditor:0x00005580df358828
    @result=
      #<struct Truemail::Auditor::Result
+       current_host_ip="127.0.0.1",
        warnings={}>,
        configuration=
         #<Truemail::Configuration:0x00005615e86327a8
@@ -980,12 +944,15 @@ Truemail.host_audit
          @whitelist_validation=false,
          @whitelisted_domains=[]>
 
-# Has PTR warning
+# Has audit warnings
 => #<Truemail::Auditor:0x00005580df358828
    @result=
      #<struct Truemail::Auditor::Result
-       warnings=
-         {:ptr=>"ptr record does not reference to current verifier domain"}>,
+       current_host_ip="127.0.0.1",
+       warnings={
+         :dns=>"A-record of verifier domain not refers to current host ip address",
+         :ptr=>"PTR-record does not reference to current verifier domain"
+       },
        configuration=
         #<Truemail::Configuration:0x00005615e86327a8
          @blacklisted_domains=[],
@@ -1004,6 +971,91 @@ Truemail.host_audit
          @whitelisted_domains=[]>
 ```
 
+### Event logger
+
+Truemail gem allows to output tracking events to stdout/file or both of these. Please note, at least one of the outputs must exist. Tracking event by default is `:error`
+
+```ruby
+Truemail.configure do |config|
+  config.logger = { tracking_event: :all, stdout: true, log_absolute_path: '/home/app/log/truemail.log' }
+end
+```
+
+#### Available tracking events
+
+- `:all`, all detected events including success validation cases
+- `:unrecognized_error`, unrecognized errors only (when `smtp_safe_check = true` and SMTP server does not return an exact answer that the email does not exist)
+- `:recognized_error`, recognized errors only
+- `:error`, recognized and unrecognized errors only
+
+### JSON serializers
+
+Truemail has built in JSON serializers for `Truemail::Auditor` and `Truemail::Validator` instances, so you can represent your host audition or email validation result as json. Also you can use [#as_json](#as_json) helper for shortcuting.
+
+#### Auditor JSON serializer
+
+```ruby
+Truemail::Log::Serializer::AuditorJson.call(Truemail.host_audit)
+
+=>
+# Serialized Truemail::Auditor instance
+{
+  "date": "2020-08-31 22:33:43 +0300",
+  "current_host_ip": "127.0.0.1",
+  "warnings": {
+    "dns": "A-record of verifier domain not refers to current host ip address", "ptr": "PTR-record does not reference to current verifier domain"
+  },
+ "configuration": {
+    "validation_type_by_domain": null,
+    "whitelist_validation": false,
+    "whitelisted_domains": null,
+    "blacklisted_domains": null,
+    "not_rfc_mx_lookup_flow": false,
+    "smtp_safe_check": false,
+    "email_pattern": "default gem value",
+    "smtp_error_body_pattern": "default gem value"
+  }
+}
+```
+
+#### Validator JSON serializer
+
+```ruby
+Truemail::Log::Serializer::ValidatorJson.call(Truemail.validate('nonexistent_email@bestweb.com.ua'))
+
+=>
+# Serialized Truemail::Validator instance
+{
+  "date": "2019-10-28 10:15:51 +0200",
+  "email": "nonexistent_email@bestweb.com.ua",
+  "validation_type": "smtp",
+  "success": false,
+  "errors": {
+    "smtp": "smtp error"
+  },
+  "smtp_debug": [
+    {
+      "mail_host": "213.180.193.89",
+      "port_opened": true,
+      "connection": true,
+      "errors": {
+        "rcptto": "550 5.7.1 No such user!\n"
+      }
+    }
+  ],
+  "configuration": {
+    "validation_type_by_domain": null,
+    "whitelist_validation": false,
+    "whitelisted_domains": null,
+    "blacklisted_domains": null,
+    "not_rfc_mx_lookup_flow": false,
+    "smtp_safe_check": false,
+    "email_pattern": "default gem value",
+    "smtp_error_body_pattern": "default gem value"
+  }
+}
+```
+
 ### Truemail helpers
 
 #### .valid?
@@ -1018,15 +1070,38 @@ Truemail.valid?('email@example.com')
 
 #### #as_json
 
-You can use `#as_json` helper for represent `Truemail::Validator` instance as json. Under the hood it uses internal json serializer [`Truemail::Log::Serializer::Json`](#json-serializer):
+You can use `#as_json` helper for represent `Truemail::Auditor` or `Truemail::Validator` instances as json. Under the hood it uses internal json `Truemail::Log::Serializer::AuditorJson` and `Truemail::Log::Serializer::ValidatorJson` [serializers](#json-serializers):
 
 ```ruby
+Truemail.host_audit.as_json
+
+=>
+# Serialized Truemail::Auditor instance
+{
+  "date": "2020-08-31 22:33:43 +0300",
+  "current_host_ip": "127.0.0.1",
+  "warnings": {
+    "dns": "A-record of verifier domain not refers to current host ip address", "ptr": "PTR-record does not reference to current verifier domain"
+  },
+ "configuration": {
+    "validation_type_by_domain": null,
+    "whitelist_validation": false,
+    "whitelisted_domains": null,
+    "blacklisted_domains": null,
+    "not_rfc_mx_lookup_flow": false,
+    "smtp_safe_check": false,
+    "email_pattern": "default gem value",
+    "smtp_error_body_pattern": "default gem value"
+  }
+}
+
+
 Truemail.validate('nonexistent_email@bestweb.com.ua').as_json
 
 =>
 # Serialized Truemail::Validator instance
 {
-  "date": "2020-02-01 10:00:00 +0200",
+  "date": "2020-05-10 10:00:00 +0200",
   "email": "nonexistent_email@bestweb.com.ua",
   "validation_type": "smtp",
   "success": false,
@@ -1048,6 +1123,7 @@ Truemail.validate('nonexistent_email@bestweb.com.ua').as_json
     "whitelist_validation": false,
     "whitelisted_domains": null,
     "blacklisted_domains": null,
+    "not_rfc_mx_lookup_flow": false,
     "smtp_safe_check": false,
     "email_pattern": "default gem value",
     "smtp_error_body_pattern": "default gem value"
@@ -1090,15 +1166,15 @@ end
 
 ## Truemail family
 
-All Truemail extensions: https://github.com/truemail-rb
+All Truemail solutions: https://truemail-rb.org
 
 | Name | Type | Description |
 | --- | --- | --- |
-| [truemail server](https://github.com/truemail-rb/truemail-rack) | ruby app | Lightweight rack based web API wrapper for Truemail |
+| [truemail server](https://github.com/truemail-rb/truemail-rack) | ruby app | Lightweight rack based web API wrapper for Truemail gem |
 | [truemail-rack-docker](https://github.com/truemail-rb/truemail-rack-docker-image) | docker image | Lightweight rack based web API [dockerized image](https://hub.docker.com/r/truemail/truemail-rack) :whale: of Truemail server |
-| [truemail-ruby-client](https://github.com/truemail-rb/truemail-ruby-client) | ruby gem | Truemail web API client library for Ruby |
-| [truemail-crystal-client](https://github.com/truemail-rb/truemail-crystal-client) | crystal shard | Truemail web API client library for Crystal |
-| [truemail-rspec](https://github.com/truemail-rb/truemail-rspec) | ruby gem | Truemail configuration and validator RSpec helpers |
+| [truemail-ruby-client](https://github.com/truemail-rb/truemail-ruby-client) | ruby gem | Web API Ruby client for Truemail Server |
+| [truemail-crystal-client](https://github.com/truemail-rb/truemail-crystal-client) | crystal shard | Web API Crystal client for Truemail Server |
+| [truemail-rspec](https://github.com/truemail-rb/truemail-rspec) | ruby gem | Truemail configuration, auditor and validator RSpec helpers |
 
 ## Contributing
 
@@ -1120,8 +1196,3 @@ Everyone interacting in the Truemail project’s codebases, issue trackers, chat
 ## Versioning
 
 Truemail uses [Semantic Versioning 2.0.0](https://semver.org)
-
----
-<a href="https://rubygarage.org/"><img src="https://rubygarage.s3.amazonaws.com/assets/assets/rg_color_logo_horizontal-919afc51a81d2e40cb6a0b43ee832e3fcd49669d06785156d2d16fd0d799f89e.png" alt="RubyGarage Logo" width="415" height="128"></a>
-
-RubyGarage is a leading software development and consulting company in Eastern Europe. Our main expertise includes Ruby and Ruby on Rails, but we successfully employ other technologies to deliver the best results to our clients. [Check out our portfolio](https://rubygarage.org/portfolio) for even more exciting works!

data/lib/truemail.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
-require 'truemail/core'
+require_relative 'truemail/core'
 
 module Truemail
   INCOMPLETE_CONFIG = 'verifier_email is required parameter'
   NOT_CONFIGURED = 'use Truemail.configure before or pass custom configuration'
+  INVALID_TYPE = 'email should be a String'
 
   class << self
     def configuration(&block)
@@ -25,10 +26,12 @@ module Truemail
     end
 
     def validate(email, custom_configuration: nil, **options)
+      check_argument_type(email)
       Truemail::Validator.new(email, configuration: determine_configuration(custom_configuration), **options).run
     end
 
     def valid?(email, **options)
+      check_argument_type(email)
       validate(email, **options).result.valid?
     end
 
@@ -38,8 +41,12 @@ module Truemail
 
     private
 
-    def raise_unless(condition, message)
-      raise Truemail::ConfigurationError, message unless condition
+    def raise_unless(condition, message, error_class = Truemail::ConfigurationError)
+      raise error_class, message unless condition
+    end
+
+    def check_argument_type(argument)
+      raise_unless(argument.is_a?(String), Truemail::INVALID_TYPE, Truemail::TypeError)
     end
 
     def determine_configuration(custom_configuration)

data/lib/truemail/audit/base.rb

@@ -3,12 +3,20 @@
 module Truemail
   module Audit
     class Base < Truemail::Worker
+      require 'net/http'
+      require 'ipaddr'
+      require 'resolv'
+
       private
 
       def add_warning(message)
         result.warnings[self.class.name.split('::').last.downcase.to_sym] = message
       end
 
+      def current_host_ip
+        result.current_host_ip
+      end
+
       def configuration
         result.configuration
       end

data/lib/truemail/audit/dns.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Truemail
+  module Audit
+    class Dns < Truemail::Audit::Base
+      VERIFIER_DOMAIN_NOT_REFER = 'A-record of verifier domain not refers to current host ip address'
+
+      def run
+        return if verifier_domain_refer_to_current_host_ip?
+        add_warning(Truemail::Audit::Dns::VERIFIER_DOMAIN_NOT_REFER)
+      end
+
+      private
+
+      def a_record
+        Truemail::Wrapper.call(configuration: configuration) do
+          Resolv::DNS.new.getaddress(verifier_domain).to_s
+        end
+      end
+
+      def verifier_domain_refer_to_current_host_ip?
+        a_record.eql?(current_host_ip)
+      end
+    end
+  end
+end

data/lib/truemail/audit/ip.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Truemail
+  module Audit
+    class Ip < Truemail::Audit::Base
+      GET_MY_IP_URL = 'https://api.ipify.org'
+      IPIFY_ERROR = 'impossible to detect current host address via third party service'
+
+      def run
+        return add_warning(Truemail::Audit::Ip::IPIFY_ERROR) unless detect_current_host_ip
+        Truemail::Audit::Dns.check(result)
+        Truemail::Audit::Ptr.check(result)
+      end
+
+      private
+
+      def detect_ip_via_ipify
+        Net::HTTP.get(URI(Truemail::Audit::Ip::GET_MY_IP_URL))
+      end
+
+      def detect_current_host_ip
+        result.current_host_ip = Truemail::Wrapper.call(configuration: configuration) do
+          detect_ip_via_ipify
+        end
+      end
+    end
+  end
+end