email_domain_checker 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16e187af255690a6a15e34fdfd3d034443ae6d335781f1b499ec0c100da6731b
-  data.tar.gz: 790adc384696330eadd419fed2cb46ff23fe0f874b59a28d7b74afc0a0bdb37b
+  metadata.gz: d7d1c8736541f32688216d1be03172bdbf164cafa12cc5931b9e90d1f95a166c
+  data.tar.gz: df42fd8b8797538a77885ceee8c86090b3f13c6b8aebe1cc1549fcf9419af028
 SHA512:
-  metadata.gz: fbd0732d8fccc016ca9ff9d302abcdc8e19f8fe2cbf392f671bb726306727cee4f5b0d2393f38736a6f9d1d4ed4db42359df667579eb6f7116d1691723b09115
-  data.tar.gz: 45cf7b78d7a22cafca5e1b236ea66426c375345acebc48b389d2230fda733d5a353a5e4cb72a18de17cc6bf6f8b21ee5ad532becd3566d010c514fbb262608f8
+  metadata.gz: 993384db88d74403bb501a6bbfd142f965341e798acdd10689eb0577f1f4b5ac93759eab7b93c8e3cd79378229f4c621e1bad0fc9c5102e357f1f2a65f2d22ce
+  data.tar.gz: 65091702811323fb963866fa603f04fc0c998bea62d261f2645cf3b4304dad85693af2ea991d74372bdb8ac85c8cee024d5fc00754ab71ae4beb1461811a4a1b

data/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.4] - 2025-11-06
+
+### Added
+- Domain filtering functionality with blacklist, whitelist, and custom checker support ([#13](https://github.com/tatematsu-k/email_domain_checker/pull/13))
+- Support for regex patterns in blacklist and whitelist configurations ([#13](https://github.com/tatematsu-k/email_domain_checker/pull/13))
+- Whitelist precedence over blacklist when both are configured ([#13](https://github.com/tatematsu-k/email_domain_checker/pull/13))
+- Comprehensive domain filtering documentation ([#13](https://github.com/tatematsu-k/email_domain_checker/pull/13))
+
 ## [0.1.3] - 2025-11-06
 
 ### Added

data/docs/configuration/domain-filtering.md

@@ -0,0 +1,213 @@
+# Domain Filtering
+
+EmailDomainChecker supports domain filtering through blacklist, whitelist, and custom checker functionality. This is useful for blocking disposable email services, restricting domains within organizations, or implementing custom business logic.
+
+## Overview
+
+Domain filtering allows you to:
+
+- **Block specific domains** using a blacklist
+- **Allow only specific domains** using a whitelist
+- **Implement custom validation logic** using a custom checker function
+
+The validation order is:
+1. Whitelist check (if configured, highest priority)
+2. Blacklist check
+3. Custom checker
+4. DNS validation
+
+## Blacklist
+
+The blacklist allows you to reject specific domains. This is useful for blocking disposable email services or known spam domains.
+
+### Basic Usage
+
+```ruby
+EmailDomainChecker.configure do |config|
+  config.blacklist_domains = [
+    "10minutemail.com",
+    "tempmail.com",
+    "guerrillamail.com"
+  ]
+end
+
+# These will be rejected
+EmailDomainChecker.valid?("user@10minutemail.com") # => false
+EmailDomainChecker.valid?("user@tempmail.com")     # => false
+
+# Other domains will pass (if they pass DNS validation)
+EmailDomainChecker.valid?("user@example.com")      # => true/false (depends on DNS)
+```
+
+### Regex Patterns
+
+You can use regex patterns to match multiple domains:
+
+```ruby
+EmailDomainChecker.configure do |config|
+  config.blacklist_domains = [
+    /.*\.spam\.com$/,      # Matches any subdomain of spam.com
+    /.*temp.*mail.*/i      # Matches domains containing "temp" and "mail" (case-insensitive)
+  ]
+end
+
+# These will be rejected
+EmailDomainChecker.valid?("user@test.spam.com")        # => false
+EmailDomainChecker.valid?("user@another.spam.com")    # => false
+EmailDomainChecker.valid?("user@tempmail.com")        # => false
+```
+
+## Whitelist
+
+The whitelist allows you to allow only specific domains. When a whitelist is configured, **only** domains matching the whitelist will be allowed (whitelist takes precedence over blacklist).
+
+### Basic Usage
+
+```ruby
+EmailDomainChecker.configure do |config|
+  config.whitelist_domains = [
+    "example.com",
+    "company.com"
+  ]
+end
+
+# These will be allowed (if they pass DNS validation)
+EmailDomainChecker.valid?("user@example.com")  # => true/false (depends on DNS)
+EmailDomainChecker.valid?("user@company.com")  # => true/false (depends on DNS)
+
+# These will be rejected (not in whitelist)
+EmailDomainChecker.valid?("user@other.com")    # => false
+EmailDomainChecker.valid?("user@gmail.com")    # => false
+```
+
+### Regex Patterns
+
+You can use regex patterns in whitelists:
+
+```ruby
+EmailDomainChecker.configure do |config|
+  config.whitelist_domains = [
+    /.*\.company\.com$/,    # Matches any subdomain of company.com
+    /.*@.*\.edu$/           # Matches any .edu domain
+  ]
+end
+
+# These will be allowed
+EmailDomainChecker.valid?("user@mail.company.com")  # => true/false (depends on DNS)
+EmailDomainChecker.valid?("user@test.company.com")  # => true/false (depends on DNS)
+EmailDomainChecker.valid?("user@university.edu")   # => true/false (depends on DNS)
+```
+
+### Whitelist Precedence
+
+When both whitelist and blacklist are configured, the whitelist takes precedence:
+
+```ruby
+EmailDomainChecker.configure do |config|
+  config.whitelist_domains = ["example.com"]
+  config.blacklist_domains = ["example.com"]  # Even if in blacklist
+end
+
+# Whitelist takes precedence
+EmailDomainChecker.valid?("user@example.com")  # => true/false (depends on DNS, but not rejected by blacklist)
+```
+
+## Custom Domain Checker
+
+The custom domain checker allows you to implement your own validation logic. This is useful for integrating with external services or implementing complex business rules.
+
+### Basic Usage
+
+```ruby
+EmailDomainChecker.configure do |config|
+  config.domain_checker = lambda do |domain|
+    # Return true to allow, false to reject
+    domain.length > 5 && !domain.start_with?("test")
+  end
+end
+
+EmailDomainChecker.valid?("user@allowed.com")  # => true/false (depends on checker and DNS)
+EmailDomainChecker.valid?("user@test.com")    # => false (rejected by custom checker)
+```
+
+### Integration with External Services
+
+```ruby
+EmailDomainChecker.configure do |config|
+  config.domain_checker = lambda do |domain|
+    # Check against disposable email service database
+    DisposableEmailService.valid?(domain)
+  end
+end
+```
+
+### Combining with Blacklist
+
+```ruby
+EmailDomainChecker.configure do |config|
+  config.blacklist_domains = ["spam.com"]
+  config.domain_checker = lambda do |domain|
+    # Custom logic: only allow domains longer than 5 characters
+    domain.length > 5
+  end
+end
+
+# Blacklist is checked first
+EmailDomainChecker.valid?("user@spam.com")     # => false (rejected by blacklist)
+
+# Then custom checker
+EmailDomainChecker.valid?("user@a.com")       # => false (rejected by custom checker)
+
+# Both checks pass
+EmailDomainChecker.valid?("user@allowed.com")  # => true/false (depends on DNS)
+```
+
+## Use Cases
+
+### Blocking Disposable Email Services
+
+```ruby
+EmailDomainChecker.configure do |config|
+  config.blacklist_domains = [
+    "10minutemail.com",
+    "tempmail.com",
+    "guerrillamail.com",
+    "mailinator.com",
+    /.*temp.*mail.*/i  # Catch variations
+  ]
+end
+```
+
+### Enterprise Domain Restriction
+
+```ruby
+EmailDomainChecker.configure do |config|
+  config.whitelist_domains = [
+    "company.com",
+    "partner.com",
+    /.*\.company\.com$/  # Allow subdomains
+  ]
+end
+```
+
+### Custom Business Logic
+
+```ruby
+EmailDomainChecker.configure do |config|
+  config.domain_checker = lambda do |domain|
+    # Check against your internal database
+    AllowedDomain.exists?(name: domain) ||
+    # Or check against external API
+    DomainValidationService.check(domain)
+  end
+end
+```
+
+## Notes
+
+- Whitelist takes precedence over blacklist
+- Custom checker is evaluated after blacklist but before DNS validation
+- All checks are case-sensitive for string matches (use regex with `i` flag for case-insensitive matching)
+- Empty arrays are treated as "no filtering" (all domains pass the filter)
+- When whitelist is configured and non-empty, only whitelisted domains can pass
+

data/docs/configuration/options.md

@@ -26,6 +26,20 @@ When test mode is enabled, domain validation will always return `true` without m
 - `cache_ttl`: Cache time-to-live in seconds (default: `3600`)
 - `redis_client`: Custom Redis client instance (only used when `cache_type` is `:redis`)
 
+### Domain Filtering Options
+
+- `blacklist_domains`: Array of domains to reject (supports strings and regex patterns) (default: `[]`)
+- `whitelist_domains`: Array of domains to allow (supports strings and regex patterns) (default: `[]`)
+- `domain_checker`: Custom domain validation function (Proc/lambda) (default: `nil`)
+
+When `whitelist_domains` is configured, only domains matching the whitelist will be allowed (whitelist takes precedence over blacklist).
+
+The validation order is:
+1. Whitelist check (if configured)
+2. Blacklist check
+3. Custom checker
+4. DNS validation
+
 ## Configuration Examples
 
 ### Basic Configuration
@@ -63,6 +77,42 @@ EmailDomainChecker.configure do |config|
 end
 ```
 
+### Blacklist Configuration
+
+```ruby
+EmailDomainChecker.configure do |config|
+  config.blacklist_domains = [
+    "10minutemail.com",
+    "tempmail.com",
+    /.*\.spam\.com$/ # Regex patterns are supported
+  ]
+end
+```
+
+### Whitelist Configuration
+
+```ruby
+EmailDomainChecker.configure do |config|
+  config.whitelist_domains = [
+    "example.com",
+    "company.com",
+    /.*\.company\.com$/ # Regex patterns are supported
+  ]
+end
+```
+
+### Custom Domain Checker
+
+```ruby
+EmailDomainChecker.configure do |config|
+  config.domain_checker = lambda do |domain|
+    # Custom validation logic
+    # Return true to allow, false to reject
+    DisposableEmailService.valid?(domain)
+  end
+end
+```
+
 ## Note on Cache Adapter Priority
 
 When both `cache_adapter_instance` and `cache_type` are set, the instance takes priority.

data/docs/index.md

@@ -9,6 +9,8 @@ Email address validation and domain checking library to prevent mail server repu
 - ✅ MX record checking
 - ✅ A record checking
 - ✅ Email normalization
+- ✅ Domain blacklist/whitelist
+- ✅ Custom domain checker
 - ✅ ActiveModel/ActiveRecord integration
 - ✅ DNS result caching (memory and Redis)
 - ✅ Test mode for development

data/lib/email_domain_checker/config.rb

@@ -13,7 +13,7 @@ module EmailDomainChecker
     }.freeze
 
     class << self
-      attr_accessor :default_options, :test_mode, :cache_enabled, :cache_type, :cache_ttl, :cache_adapter, :cache_adapter_instance, :redis_client
+      attr_accessor :default_options, :test_mode, :cache_enabled, :cache_type, :cache_ttl, :cache_adapter, :cache_adapter_instance, :redis_client, :blacklist_domains, :whitelist_domains, :domain_checker
 
       def configure(options = {}, &block)
         if block_given?
@@ -36,6 +36,9 @@ module EmailDomainChecker
         @cache_adapter = nil
         @cache_adapter_instance = nil
         @redis_client = nil
+        @blacklist_domains = []
+        @whitelist_domains = []
+        @domain_checker = nil
       end
 
       def test_mode=(value)
@@ -116,7 +119,7 @@ module EmailDomainChecker
       end
     end
 
-    attr_accessor :test_mode, :cache_enabled, :cache_type, :cache_ttl, :cache_adapter_instance, :redis_client
+    attr_accessor :test_mode, :cache_enabled, :cache_type, :cache_ttl, :cache_adapter_instance, :redis_client, :blacklist_domains, :whitelist_domains, :domain_checker
 
     def initialize
       @test_mode = self.class.test_mode || false
@@ -125,6 +128,9 @@ module EmailDomainChecker
       @cache_ttl = self.class.cache_ttl || 3600
       @cache_adapter_instance = self.class.cache_adapter_instance
       @redis_client = self.class.redis_client
+      @blacklist_domains = self.class.blacklist_domains || []
+      @whitelist_domains = self.class.whitelist_domains || []
+      @domain_checker = self.class.domain_checker
     end
 
     def test_mode=(value)
@@ -164,6 +170,21 @@ module EmailDomainChecker
       self.class.reset_cache_adapter_if_redis
     end
 
+    def blacklist_domains=(value)
+      @blacklist_domains = value || []
+      self.class.blacklist_domains = value || []
+    end
+
+    def whitelist_domains=(value)
+      @whitelist_domains = value || []
+      self.class.whitelist_domains = value || []
+    end
+
+    def domain_checker=(value)
+      @domain_checker = value
+      self.class.domain_checker = value
+    end
+
     reset
   end
 end

data/lib/email_domain_checker/domain_validator.rb

@@ -20,6 +20,20 @@ module EmailDomainChecker
     def valid?(domain)
       return false if domain.nil? || domain.empty?
 
+      # Check whitelist first (if configured)
+      unless Config.whitelist_domains.nil? || Config.whitelist_domains.empty?
+        return whitelisted?(domain)
+      end
+
+      # Check blacklist
+      return false if blacklisted?(domain)
+
+      # Check custom domain checker
+      if Config.domain_checker
+        custom_result = Config.domain_checker.call(domain)
+        return false unless custom_result
+      end
+
       # Skip DNS checks if test mode is enabled
       return true if Config.test_mode?
 
@@ -28,6 +42,33 @@ module EmailDomainChecker
 
     private
 
+    def whitelisted?(domain)
+      return false if Config.whitelist_domains.nil? || Config.whitelist_domains.empty?
+
+      Config.whitelist_domains.any? do |pattern|
+        matches_pattern?(domain, pattern)
+      end
+    end
+
+    def blacklisted?(domain)
+      return false if Config.blacklist_domains.nil? || Config.blacklist_domains.empty?
+
+      Config.blacklist_domains.any? do |pattern|
+        matches_pattern?(domain, pattern)
+      end
+    end
+
+    def matches_pattern?(domain, pattern)
+      case pattern
+      when Regexp
+        pattern.match?(domain)
+      when String
+        pattern == domain
+      else
+        false
+      end
+    end
+
     def check_domain_records(domain)
       if options[:check_mx]
         return false unless dns_resolver.has_mx_record?(domain)

data/lib/email_domain_checker/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module EmailDomainChecker
-  VERSION = "0.1.3"
+  VERSION = "0.1.4"
 end

data/mkdocs.yml

@@ -57,6 +57,7 @@ nav:
     - ActiveModel Integration: usage/activemodel-integration.md
   - Configuration:
     - Configuration Options: configuration/options.md
+    - Domain Filtering: configuration/domain-filtering.md
     - Test Mode: configuration/test-mode.md
     - Cache Configuration: configuration/cache.md
   - Contributing: contributing.md

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: email_domain_checker
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Koki Tatematsu
@@ -79,6 +79,7 @@ files:
 - Rakefile
 - docs-templates/index.html
 - docs/configuration/cache.md
+- docs/configuration/domain-filtering.md
 - docs/configuration/options.md
 - docs/configuration/test-mode.md
 - docs/contributing.md