truemail 1.7.1 → 2.0.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (31) hide show
  1. checksums.yaml +4 -4
  2. data/.circleci/config.yml +1 -1
  3. data/.codeclimate.yml +1 -1
  4. data/.github/ISSUE_TEMPLATE.md +3 -3
  5. data/.github/PULL_REQUEST_TEMPLATE.md +1 -1
  6. data/.reek.yml +4 -0
  7. data/.rubocop.yml +177 -6
  8. data/CHANGELOG.md +149 -22
  9. data/Gemfile.lock +44 -38
  10. data/LICENSE.txt +1 -1
  11. data/README.md +162 -102
  12. data/lib/truemail.rb +10 -3
  13. data/lib/truemail/audit/base.rb +8 -0
  14. data/lib/truemail/audit/dns.rb +26 -0
  15. data/lib/truemail/audit/ip.rb +28 -0
  16. data/lib/truemail/audit/ptr.rb +8 -37
  17. data/lib/truemail/auditor.rb +7 -5
  18. data/lib/truemail/configuration.rb +8 -2
  19. data/lib/truemail/core.rb +28 -22
  20. data/lib/truemail/executor.rb +11 -0
  21. data/lib/truemail/log/serializer/auditor_json.rb +25 -0
  22. data/lib/truemail/log/serializer/base.rb +17 -42
  23. data/lib/truemail/log/serializer/validator_base.rb +45 -0
  24. data/lib/truemail/log/serializer/{json.rb → validator_json.rb} +1 -1
  25. data/lib/truemail/log/serializer/{text.rb → validator_text.rb} +2 -2
  26. data/lib/truemail/logger.rb +1 -1
  27. data/lib/truemail/validate/smtp/request.rb +2 -3
  28. data/lib/truemail/validator.rb +4 -4
  29. data/lib/truemail/version.rb +1 -1
  30. data/truemail.gemspec +17 -9
  31. metadata +49 -27
data/Gemfile.lock CHANGED
@@ -1,40 +1,39 @@
1
1
  PATH
2
2
  remote: .
3
3
  specs:
4
- truemail (1.7.1)
4
+ truemail (2.0.0)
5
5
  simpleidn (~> 0.1.1)
6
6
 
7
7
  GEM
8
8
  remote: https://rubygems.org/
9
9
  specs:
10
- ast (2.4.0)
11
- bundler-audit (0.6.1)
10
+ ast (2.4.1)
11
+ bundler-audit (0.7.0.1)
12
12
  bundler (>= 1.2.0, < 3)
13
- thor (~> 0.18)
13
+ thor (>= 0.18, < 2)
14
14
  byebug (11.1.3)
15
- childprocess (3.0.0)
16
- coderay (1.1.2)
15
+ childprocess (4.0.0)
16
+ coderay (1.1.3)
17
17
  colorize (0.8.1)
18
- diff-lcs (1.3)
18
+ diff-lcs (1.4.4)
19
19
  docile (1.3.2)
20
20
  fasterer (0.8.3)
21
21
  colorize (~> 0.7)
22
22
  ruby_parser (>= 3.14.1)
23
- ffaker (2.14.0)
23
+ ffaker (2.17.0)
24
24
  iniparse (1.5.0)
25
- jaro_winkler (1.5.4)
26
- json (2.3.0)
25
+ json (2.3.1)
27
26
  json_matchers (0.11.1)
28
27
  json_schema
29
- json_schema (0.20.8)
28
+ json_schema (0.20.9)
30
29
  kwalify (0.7.2)
31
30
  method_source (1.0.0)
32
- overcommit (0.53.0)
33
- childprocess (>= 0.6.3, < 4)
31
+ overcommit (0.55.0)
32
+ childprocess (>= 0.6.3, < 5)
34
33
  iniparse (~> 1.4)
35
- parallel (1.19.1)
36
- parser (2.7.1.2)
37
- ast (~> 2.4.0)
34
+ parallel (1.19.2)
35
+ parser (2.7.1.4)
36
+ ast (~> 2.4.1)
38
37
  pry (0.13.1)
39
38
  coderay (~> 1.1)
40
39
  method_source (~> 1.0)
@@ -44,11 +43,13 @@ GEM
44
43
  psych (3.1.0)
45
44
  rainbow (3.0.0)
46
45
  rake (13.0.1)
47
- reek (6.0.0)
46
+ reek (6.0.1)
48
47
  kwalify (~> 0.7.0)
49
48
  parser (>= 2.5.0.0, < 2.8, != 2.5.1.1)
50
49
  psych (~> 3.1.0)
51
50
  rainbow (>= 2.0, < 4.0)
51
+ regexp_parser (1.8.0)
52
+ rexml (3.2.4)
52
53
  rspec (3.9.0)
53
54
  rspec-core (~> 3.9.0)
54
55
  rspec-expectations (~> 3.9.0)
@@ -62,21 +63,26 @@ GEM
62
63
  diff-lcs (>= 1.2.0, < 2.0)
63
64
  rspec-support (~> 3.9.0)
64
65
  rspec-support (3.9.3)
65
- rubocop (0.79.0)
66
- jaro_winkler (~> 1.5.1)
66
+ rubocop (0.91.0)
67
67
  parallel (~> 1.10)
68
- parser (>= 2.7.0.1)
68
+ parser (>= 2.7.1.1)
69
69
  rainbow (>= 2.2.2, < 4.0)
70
+ regexp_parser (>= 1.7)
71
+ rexml
72
+ rubocop-ast (>= 0.4.0, < 1.0)
70
73
  ruby-progressbar (~> 1.7)
71
- unicode-display_width (>= 1.4.0, < 1.7)
72
- rubocop-performance (1.5.2)
73
- rubocop (>= 0.71.0)
74
- rubocop-rspec (1.39.0)
75
- rubocop (>= 0.68.1)
74
+ unicode-display_width (>= 1.4.0, < 2.0)
75
+ rubocop-ast (0.4.2)
76
+ parser (>= 2.7.1.4)
77
+ rubocop-performance (1.8.1)
78
+ rubocop (>= 0.87.0)
79
+ rubocop-ast (>= 0.4.0)
80
+ rubocop-rspec (1.43.2)
81
+ rubocop (~> 0.87)
76
82
  ruby-progressbar (1.10.1)
77
- ruby_parser (3.14.2)
83
+ ruby_parser (3.15.0)
78
84
  sexp_processor (~> 4.9)
79
- sexp_processor (4.14.1)
85
+ sexp_processor (4.15.1)
80
86
  simplecov (0.17.1)
81
87
  docile (~> 1.1)
82
88
  json (>= 1.8, < 3)
@@ -84,35 +90,35 @@ GEM
84
90
  simplecov-html (0.10.2)
85
91
  simpleidn (0.1.1)
86
92
  unf (~> 0.1.4)
87
- thor (0.20.3)
88
- truemail-rspec (0.1.2)
93
+ thor (1.0.1)
94
+ truemail-rspec (0.2.1)
89
95
  rspec (~> 3.9)
90
96
  truemail (~> 1.4, >= 1.4.1)
91
97
  unf (0.1.4)
92
98
  unf_ext
93
99
  unf_ext (0.0.7.7)
94
- unicode-display_width (1.6.1)
100
+ unicode-display_width (1.7.0)
95
101
 
96
102
  PLATFORMS
97
103
  ruby
98
104
 
99
105
  DEPENDENCIES
100
106
  bundler (~> 1.16)
101
- bundler-audit (~> 0.6.1)
107
+ bundler-audit (~> 0.7.0.1)
102
108
  fasterer (~> 0.8.3)
103
- ffaker (~> 2.14)
109
+ ffaker (~> 2.17)
104
110
  json_matchers (~> 0.11.1)
105
- overcommit (~> 0.53.0)
111
+ overcommit (~> 0.55.0)
106
112
  pry-byebug (~> 3.9)
107
113
  rake (~> 13.0, >= 13.0.1)
108
- reek (~> 6.0)
114
+ reek (~> 6.0, >= 6.0.1)
109
115
  rspec (~> 3.9)
110
- rubocop (~> 0.79.0)
111
- rubocop-performance (~> 1.5, >= 1.5.2)
112
- rubocop-rspec (~> 1.39)
116
+ rubocop (~> 0.91.0)
117
+ rubocop-performance (~> 1.8, >= 1.8.1)
118
+ rubocop-rspec (~> 1.43, >= 1.43.2)
113
119
  simplecov (~> 0.17.1)
114
120
  truemail!
115
- truemail-rspec (~> 0.1.2)
121
+ truemail-rspec (~> 0.2.1)
116
122
 
117
123
  BUNDLED WITH
118
124
  1.16.6
data/LICENSE.txt CHANGED
@@ -1,6 +1,6 @@
1
1
  The MIT License (MIT)
2
2
 
3
- Copyright (c) 2019 Vladislav Trotsenko
3
+ Copyright (c) 2019-2020 Vladislav Trotsenko
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
data/README.md CHANGED
@@ -1,9 +1,11 @@
1
- # <img src='https://repository-images.githubusercontent.com/173723932/6dffee00-e88e-11e9-94b6-c97aacc0df00' height='250' alt='Truemail - configurable framework agnostic plain Ruby email validator' />
1
+ # ![Truemail - configurable framework agnostic plain Ruby email validator](https://truemail-rb.org/assets/images/truemail_logo.png)
2
2
 
3
- [![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)
3
+ [![Maintainability](https://api.codeclimate.com/v1/badges/0fea6d2e64d78d66b149/maintainability)](https://codeclimate.com/github/truemail-rb/truemail/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/0fea6d2e64d78d66b149/test_coverage)](https://codeclimate.com/github/truemail-rb/truemail/test_coverage) [![CircleCI](https://circleci.com/gh/truemail-rb/truemail/tree/develop.svg?style=svg)](https://circleci.com/gh/truemail-rb/truemail/tree/develop) [![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)
4
4
 
5
5
  Configurable framework agnostic plain Ruby email validator. Verify email via Regex, DNS and SMTP. Be sure that email address valid and exists.
6
6
 
7
+ > Actual and maintainable documentation :books: for developers is living [here](https://truemail-rb.org/truemail-gem).
8
+
7
9
  ## Table of Contents
8
10
 
9
11
  - [Synopsis](#synopsis)
@@ -32,11 +34,16 @@ Configurable framework agnostic plain Ruby email validator. Verify email via Reg
32
34
  - [SMTP validation](#smtp-validation)
33
35
  - [SMTP safe check disabled](#smtp-safe-check-disabled)
34
36
  - [SMTP safe check enabled](#smtp-safe-check-enabled)
35
- - [Event logger](#event-logger)
36
- - [Available tracking events](#available-tracking-events)
37
- - [JSON serializer](#json-serializer)
38
37
  - [Host audit features](#host-audit-features)
38
+ - [IP audit](#ip-audit)
39
+ - [DNS audit](#dns-audit)
39
40
  - [PTR audit](#ptr-audit)
41
+ - [Example of using](#example-of-using)
42
+ - [Event logger](#event-logger)
43
+ - [Available tracking events](#available-tracking-events)
44
+ - [JSON serializers](#json-serializers)
45
+ - [Auditor JSON serializer](#auditor-json-serializer)
46
+ - [Validator JSON serializer](#validator-json-serializer)
40
47
  - [Truemail helpers](#truemail-helpers)
41
48
  - [.valid?](#valid)
42
49
  - [#as_json](#as_json)
@@ -48,11 +55,10 @@ Configurable framework agnostic plain Ruby email validator. Verify email via Reg
48
55
  - [Credits](#credits)
49
56
  - [Versioning](#versioning)
50
57
  - [Changelog](CHANGELOG.md)
51
- - [Wiki](https://github.com/rubygarage/truemail/wiki)
52
58
 
53
59
  ## Synopsis
54
60
 
55
- 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.
61
+ 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.
56
62
 
57
63
  **Syntax Checking**: Checks the email addresses via regex pattern.
58
64
 
@@ -70,7 +76,8 @@ Also Truemail gem allows performing an audit of the host in which runs.
70
76
  - Whitelist/blacklist validation layers
71
77
  - Simple SMTP debugger
72
78
  - Event logger
73
- - JSON serializer
79
+ - Host auditor tools (helps to detect common host problems interfering to proper email verification)
80
+ - JSON serializers
74
81
 
75
82
  ## Requirements
76
83
 
@@ -120,7 +127,7 @@ You can use global gem configuration or custom independent configuration. Availa
120
127
 
121
128
  #### Setting global configuration
122
129
 
123
- To have an access for ```Truemail.configuration``` and gem configuration features, you must configure it first as in the example below:
130
+ To have an access for `Truemail.configuration` and gem configuration features, you must configure it first as in the example below:
124
131
 
125
132
  ```ruby
126
133
  require 'truemail'
@@ -282,11 +289,12 @@ Please note, you should have global or custom configuration for use Truemail gem
282
289
 
283
290
  #### Whitelist/Blacklist check
284
291
 
285
- Whitelist/Blacklist check is zero validation level. You can define white and black list domains. It means that validation of email which contains whitelisted domain always will return ```true```, and for blacklisted domain will return ```false```.
292
+ Whitelist/Blacklist check is zero validation level. You can define white and black list domains. It means that validation of email which contains whitelisted domain always will return `true`, and for blacklisted domain will return `false`.
286
293
 
287
- Please note, other validations will not processed even if it was defined in ```validation_type_for```.
294
+ Please note, other validations will not processed even if it was defined in `validation_type_for`.
288
295
 
289
296
  **Sequence of domain list check:**
297
+
290
298
  1. Whitelist check
291
299
  2. Whitelist validation check
292
300
  3. Blacklist check
@@ -349,8 +357,7 @@ Truemail.configure do |config|
349
357
  end
350
358
  ```
351
359
 
352
- When email domain in whitelist and ```whitelist_validation``` is sets equal to ```true``` validation type will be passed to other validators.
353
- Validation of email which not contains whitelisted domain always will return ```false```.
360
+ When email domain in whitelist and `whitelist_validation` is sets equal to `true` validation type will be passed to other validators. Validation of email which not contains whitelisted domain always will return `false`.
354
361
 
355
362
  ###### Email has whitelisted domain
356
363
 
@@ -452,7 +459,7 @@ Truemail.validate('email@black-domain.com')
452
459
 
453
460
  ##### Duplication case
454
461
 
455
- Validation result for this email returns ```true```, because it was found in whitelisted domains list first. Also ```validation_type``` for this case will be redefined.
462
+ Validation result for this email returns `true`, because it was found in whitelisted domains list first. Also `validation_type` for this case will be redefined.
456
463
 
457
464
  ```ruby
458
465
  Truemail.validate('email@somedomain.com')
@@ -584,7 +591,7 @@ In fact it's DNS validation because it checks not MX records only. DNS validatio
584
591
  [Whitelist/Blacklist] -> [Regex validation] -> [MX validation]
585
592
  ```
586
593
 
587
- Please note, Truemail MX validator [not performs](https://github.com/rubygarage/truemail/issues/26) strict compliance of the [RFC 5321](https://tools.ietf.org/html/rfc5321#section-5) standard for best validation outcome.
594
+ Please note, Truemail MX validator [not performs](https://github.com/truemail-rb/truemail/issues/26) strict compliance of the [RFC 5321](https://tools.ietf.org/html/rfc5321#section-5) standard for best validation outcome.
588
595
 
589
596
  ##### RFC MX lookup flow
590
597
 
@@ -681,13 +688,13 @@ SMTP validation is a final, third validation level. This type of validation trie
681
688
  [Whitelist/Blacklist] -> [Regex validation] -> [MX validation] -> [SMTP validation]
682
689
  ```
683
690
 
684
- If total count of MX servers is equal to one, ```Truemail::Smtp``` validator will use value from ```Truemail.configuration.connection_attempts``` as connection attempts. By default it's equal 2.
691
+ If total count of MX servers is equal to one, `Truemail::Smtp` validator will use value from `Truemail.configuration.connection_attempts` as connection attempts. By default it's equal `2`.
685
692
 
686
693
  By default, you don't need pass with-parameter to use it. Example of usage is specified below:
687
694
 
688
695
  ##### SMTP safe check disabled
689
696
 
690
- With ```smtp_safe_check = false```
697
+ With `smtp_safe_check = false`
691
698
 
692
699
  ```ruby
693
700
  require 'truemail'
@@ -750,10 +757,7 @@ Truemail.validate('email@example.com')
750
757
  #<struct Truemail::Validate::Smtp::Response
751
758
  port_opened=true,
752
759
  connection=true,
753
- helo=
754
- #<Net::SMTP::Response:0x0000000002d5aca8
755
- @status="250",
756
- @string="250 127.0.1.1 Hello example.com\n">,
760
+ helo=true,
757
761
  mailfrom=
758
762
  #<Net::SMTP::Response:0x0000000002d5a618
759
763
  @status="250",
@@ -781,7 +785,7 @@ Truemail.validate('email@example.com')
781
785
 
782
786
  ##### SMTP safe check enabled
783
787
 
784
- With ```smtp_safe_check = true```
788
+ With `smtp_safe_check = true`
785
789
 
786
790
  ```ruby
787
791
  require 'truemail'
@@ -817,10 +821,7 @@ Truemail.validate('email@example.com')
817
821
  #<struct Truemail::Validate::Smtp::Response
818
822
  port_opened=true,
819
823
  connection=false,
820
- helo=
821
- #<Net::SMTP::Response:0x0000000002c934c8
822
- @status="250",
823
- @string="250 127.0.1.1\n">,
824
+ helo=true,
824
825
  mailfrom=false,
825
826
  rcptto=nil,
826
827
  errors={:mailfrom=>"554 5.7.1 Client host blocked\n", :connection=>"server dropped connection after response"}>>,]>,
@@ -866,10 +867,7 @@ Truemail.validate('email@example.com')
866
867
  #<struct Truemail::Validate::Smtp::Response
867
868
  port_opened=true,
868
869
  connection=true,
869
- helo=
870
- #<Net::SMTP::Response:0x0000000002d5aca8
871
- @status="250",
872
- @string="250 127.0.1.1 Hello example.com\n">,
870
+ helo=true,
873
871
  mailfrom=#<Net::SMTP::Response:0x0000000002d5a618 @status="250", @string="250 OK\n">,
874
872
  rcptto=false,
875
873
  errors={:rcptto=>"550 User not found\n"}>>]>,
@@ -892,77 +890,33 @@ Truemail.validate('email@example.com')
892
890
  @validation_type=:smtp>
893
891
  ```
894
892
 
895
- ### Event logger
893
+ ### Host audit features
896
894
 
897
- 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`
895
+ 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.
898
896
 
899
- ```ruby
900
- Truemail.configure do |config|
901
- config.logger = { tracking_event: :all, stdout: true, log_absolute_path: '/home/app/log/truemail.log' }
902
- end
903
- ```
897
+ #### IP audit
904
898
 
905
- #### Available tracking events
899
+ Checks is current Truemail host has proper internet connection and detects current host ip address.
906
900
 
907
- - `:all`, all detected events including success validation cases
908
- - `: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)
909
- - `:recognized_error`, recognized errors only
910
- - `:error`, recognized and unrecognized errors only
911
-
912
- ### JSON serializer
901
+ #### DNS audit
913
902
 
914
- Truemail has built in JSON serializer for `Truemail::Validator` instance, so you can represent your email validation result as json.
915
-
916
- ```ruby
917
- Truemail::Log::Serializer::Json.call(Truemail.validate('nonexistent_email@bestweb.com.ua'))
918
-
919
- =>
920
- # Serialized Truemail::Validator instance
921
- {
922
- "date": "2019-10-28 10:15:51 +0200",
923
- "email": "nonexistent_email@bestweb.com.ua",
924
- "validation_type": "smtp",
925
- "success": false,
926
- "errors": {
927
- "smtp": "smtp error"
928
- },
929
- "smtp_debug": [
930
- {
931
- "mail_host": "213.180.193.89",
932
- "port_opened": true,
933
- "connection": true,
934
- "errors": {
935
- "rcptto": "550 5.7.1 No such user!\n"
936
- }
937
- }
938
- ],
939
- "configuration": {
940
- "validation_type_by_domain": null,
941
- "whitelist_validation": false,
942
- "whitelisted_domains": null,
943
- "blacklisted_domains": null,
944
- "not_rfc_mx_lookup_flow": false,
945
- "smtp_safe_check": false,
946
- "email_pattern": "default gem value",
947
- "smtp_error_body_pattern": "default gem value"
948
- }
949
- }
950
- ```
951
-
952
- ### Host audit features
953
-
954
- Truemail gem allows performing an audit of the host in which runs. Only PTR record audit performs for today.
903
+ Checks is verifier domain refer to current Truemail host IP address.
955
904
 
956
905
  #### PTR audit
957
906
 
958
907
  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.
959
908
 
909
+ Checks is PTR record exists for your Truemail host ip address exists and refers to current verifier domain.
910
+
911
+ #### Example of using
912
+
960
913
  ```ruby
961
914
  Truemail.host_audit
962
915
  # Everything is good
963
916
  => #<Truemail::Auditor:0x00005580df358828
964
917
  @result=
965
918
  #<struct Truemail::Auditor::Result
919
+ current_host_ip="127.0.0.1",
966
920
  warnings={}>,
967
921
  configuration=
968
922
  #<Truemail::Configuration:0x00005615e86327a8
@@ -981,12 +935,15 @@ Truemail.host_audit
981
935
  @whitelist_validation=false,
982
936
  @whitelisted_domains=[]>
983
937
 
984
- # Has PTR warning
938
+ # Has audit warnings
985
939
  => #<Truemail::Auditor:0x00005580df358828
986
940
  @result=
987
941
  #<struct Truemail::Auditor::Result
988
- warnings=
989
- {:ptr=>"ptr record does not reference to current verifier domain"}>,
942
+ current_host_ip="127.0.0.1",
943
+ warnings={
944
+ :dns=>"A-record of verifier domain not refers to current host ip address",
945
+ :ptr=>"PTR-record does not reference to current verifier domain"
946
+ },
990
947
  configuration=
991
948
  #<Truemail::Configuration:0x00005615e86327a8
992
949
  @blacklisted_domains=[],
@@ -1005,6 +962,91 @@ Truemail.host_audit
1005
962
  @whitelisted_domains=[]>
1006
963
  ```
1007
964
 
965
+ ### Event logger
966
+
967
+ 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`
968
+
969
+ ```ruby
970
+ Truemail.configure do |config|
971
+ config.logger = { tracking_event: :all, stdout: true, log_absolute_path: '/home/app/log/truemail.log' }
972
+ end
973
+ ```
974
+
975
+ #### Available tracking events
976
+
977
+ - `:all`, all detected events including success validation cases
978
+ - `: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)
979
+ - `:recognized_error`, recognized errors only
980
+ - `:error`, recognized and unrecognized errors only
981
+
982
+ ### JSON serializers
983
+
984
+ 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.
985
+
986
+ #### Auditor JSON serializer
987
+
988
+ ```ruby
989
+ Truemail::Log::Serializer::AuditorJson.call(Truemail.host_audit)
990
+
991
+ =>
992
+ # Serialized Truemail::Auditor instance
993
+ {
994
+ "date": "2020-08-31 22:33:43 +0300",
995
+ "current_host_ip": "127.0.0.1",
996
+ "warnings": {
997
+ "dns": "A-record of verifier domain not refers to current host ip address", "ptr": "PTR-record does not reference to current verifier domain"
998
+ },
999
+ "configuration": {
1000
+ "validation_type_by_domain": null,
1001
+ "whitelist_validation": false,
1002
+ "whitelisted_domains": null,
1003
+ "blacklisted_domains": null,
1004
+ "not_rfc_mx_lookup_flow": false,
1005
+ "smtp_safe_check": false,
1006
+ "email_pattern": "default gem value",
1007
+ "smtp_error_body_pattern": "default gem value"
1008
+ }
1009
+ }
1010
+ ```
1011
+
1012
+ #### Validator JSON serializer
1013
+
1014
+ ```ruby
1015
+ Truemail::Log::Serializer::ValidatorJson.call(Truemail.validate('nonexistent_email@bestweb.com.ua'))
1016
+
1017
+ =>
1018
+ # Serialized Truemail::Validator instance
1019
+ {
1020
+ "date": "2019-10-28 10:15:51 +0200",
1021
+ "email": "nonexistent_email@bestweb.com.ua",
1022
+ "validation_type": "smtp",
1023
+ "success": false,
1024
+ "errors": {
1025
+ "smtp": "smtp error"
1026
+ },
1027
+ "smtp_debug": [
1028
+ {
1029
+ "mail_host": "213.180.193.89",
1030
+ "port_opened": true,
1031
+ "connection": true,
1032
+ "errors": {
1033
+ "rcptto": "550 5.7.1 No such user!\n"
1034
+ }
1035
+ }
1036
+ ],
1037
+ "configuration": {
1038
+ "validation_type_by_domain": null,
1039
+ "whitelist_validation": false,
1040
+ "whitelisted_domains": null,
1041
+ "blacklisted_domains": null,
1042
+ "not_rfc_mx_lookup_flow": false,
1043
+ "smtp_safe_check": false,
1044
+ "email_pattern": "default gem value",
1045
+ "smtp_error_body_pattern": "default gem value"
1046
+ }
1047
+ }
1048
+ ```
1049
+
1008
1050
  ### Truemail helpers
1009
1051
 
1010
1052
  #### .valid?
@@ -1019,9 +1061,32 @@ Truemail.valid?('email@example.com')
1019
1061
 
1020
1062
  #### #as_json
1021
1063
 
1022
- 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):
1064
+ 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):
1023
1065
 
1024
1066
  ```ruby
1067
+ Truemail.host_audit.as_json
1068
+
1069
+ =>
1070
+ # Serialized Truemail::Auditor instance
1071
+ {
1072
+ "date": "2020-08-31 22:33:43 +0300",
1073
+ "current_host_ip": "127.0.0.1",
1074
+ "warnings": {
1075
+ "dns": "A-record of verifier domain not refers to current host ip address", "ptr": "PTR-record does not reference to current verifier domain"
1076
+ },
1077
+ "configuration": {
1078
+ "validation_type_by_domain": null,
1079
+ "whitelist_validation": false,
1080
+ "whitelisted_domains": null,
1081
+ "blacklisted_domains": null,
1082
+ "not_rfc_mx_lookup_flow": false,
1083
+ "smtp_safe_check": false,
1084
+ "email_pattern": "default gem value",
1085
+ "smtp_error_body_pattern": "default gem value"
1086
+ }
1087
+ }
1088
+
1089
+
1025
1090
  Truemail.validate('nonexistent_email@bestweb.com.ua').as_json
1026
1091
 
1027
1092
  =>
@@ -1092,19 +1157,19 @@ end
1092
1157
 
1093
1158
  ## Truemail family
1094
1159
 
1095
- All Truemail extensions: https://github.com/truemail-rb
1160
+ All Truemail solutions: https://truemail-rb.org
1096
1161
 
1097
1162
  | Name | Type | Description |
1098
1163
  | --- | --- | --- |
1099
- | [truemail server](https://github.com/truemail-rb/truemail-rack) | ruby app | Lightweight rack based web API wrapper for Truemail |
1164
+ | [truemail server](https://github.com/truemail-rb/truemail-rack) | ruby app | Lightweight rack based web API wrapper for Truemail gem |
1100
1165
  | [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 |
1101
- | [truemail-ruby-client](https://github.com/truemail-rb/truemail-ruby-client) | ruby gem | Truemail web API client library for Ruby |
1102
- | [truemail-crystal-client](https://github.com/truemail-rb/truemail-crystal-client) | crystal shard | Truemail web API client library for Crystal |
1103
- | [truemail-rspec](https://github.com/truemail-rb/truemail-rspec) | ruby gem | Truemail configuration and validator RSpec helpers |
1166
+ | [truemail-ruby-client](https://github.com/truemail-rb/truemail-ruby-client) | ruby gem | Web API Ruby client for Truemail Server |
1167
+ | [truemail-crystal-client](https://github.com/truemail-rb/truemail-crystal-client) | crystal shard | Web API Crystal client for Truemail Server |
1168
+ | [truemail-rspec](https://github.com/truemail-rb/truemail-rspec) | ruby gem | Truemail configuration, auditor and validator RSpec helpers |
1104
1169
 
1105
1170
  ## Contributing
1106
1171
 
1107
- Bug reports and pull requests are welcome on GitHub at https://github.com/rubygarage/truemail. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct. Please check the [open tikets](https://github.com/rubygarage/truemail/issues). Be shure to follow Contributor Code of Conduct below and our [Contributing Guidelines](CONTRIBUTING.md).
1172
+ Bug reports and pull requests are welcome on GitHub at https://github.com/truemail-rb/truemail. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct. Please check the [open tikets](https://github.com/truemail-rb/truemail/issues). Be shure to follow Contributor Code of Conduct below and our [Contributing Guidelines](CONTRIBUTING.md).
1108
1173
 
1109
1174
  ## License
1110
1175
 
@@ -1116,14 +1181,9 @@ Everyone interacting in the Truemail project’s codebases, issue trackers, chat
1116
1181
 
1117
1182
  ## Credits
1118
1183
 
1119
- - [The Contributors](https://github.com/rubygarage/truemail/graphs/contributors) for code and awesome suggestions
1120
- - [The Stargazers](https://github.com/rubygarage/truemail/stargazers) for showing their support
1184
+ - [The Contributors](https://github.com/truemail-rb/truemail/graphs/contributors) for code and awesome suggestions
1185
+ - [The Stargazers](https://github.com/truemail-rb/truemail/stargazers) for showing their support
1121
1186
 
1122
1187
  ## Versioning
1123
1188
 
1124
1189
  Truemail uses [Semantic Versioning 2.0.0](https://semver.org)
1125
-
1126
- ---
1127
- <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>
1128
-
1129
- 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!