email_domain_checker 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9482f21ae74333979292271bf830aa22164a859388ba73b29a090118185ac797
-  data.tar.gz: 12fa14a045d73af82ff4d179c55d9f7c425ec25a1bc171d3328e60f5045f92de
+  metadata.gz: d7d1c8736541f32688216d1be03172bdbf164cafa12cc5931b9e90d1f95a166c
+  data.tar.gz: df42fd8b8797538a77885ceee8c86090b3f13c6b8aebe1cc1549fcf9419af028
 SHA512:
-  metadata.gz: ab00a7b94993e50f3e5e8c4b7d7fa74c270a77778c4bd7c5796f84420fe1ffb0c929ec3efa4999d573ba38325e431cca20359e55dcfe68d4b73f67367f57a92d
-  data.tar.gz: 7a1f651e88f540389f8d213e381a37047c96370d3ff2bb1b4bd8a3655045ac9bb9cf749695ca8c774d2cca38050028e11468f181c883ff6b391abaf57f1d544a
+  metadata.gz: 993384db88d74403bb501a6bbfd142f965341e798acdd10689eb0577f1f4b5ac93759eab7b93c8e3cd79378229f4c621e1bad0fc9c5102e357f1f2a65f2d22ce
+  data.tar.gz: 65091702811323fb963866fa603f04fc0c998bea62d261f2645cf3b4304dad85693af2ea991d74372bdb8ac85c8cee024d5fc00754ab71ae4beb1461811a4a1b

data/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [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
+- DNS validation result caching functionality with memory and Redis adapters, custom adapter support, and Rails-style `cache.with` method ([#7](https://github.com/tatematsu-k/email_domain_checker/pull/7))
+
+### Documentation
+- Added comprehensive documentation site with MkDocs including installation guide, usage examples, configuration options, and ActiveModel integration documentation
+
 ## [0.1.2] - 2025-11-05
 
 ### Added

data/README.md

@@ -18,9 +18,7 @@ Or install it yourself as:
 
     $ gem install email_domain_checker
 
-## Usage
-
-### Module-level convenience methods
+## Quick Start
 
 ```ruby
 require 'email_domain_checker'
@@ -28,137 +26,54 @@ require 'email_domain_checker'
 # Quick validation
 EmailDomainChecker.valid?("user@example.com", validate_domain: false) # => true
 
-# Format validation only
-EmailDomainChecker.format_valid?("user@example.com") # => true
-
-# Domain validation only
+# Domain validation with MX records
 EmailDomainChecker.domain_valid?("user@example.com", check_mx: true) # => true/false
 
 # Normalize email
 EmailDomainChecker.normalize("User@Example.COM") # => "user@example.com"
-
-# Configure default options globally
-EmailDomainChecker.configure(timeout: 10, check_mx: true)
-
-# Enable test mode (skips DNS checks)
-EmailDomainChecker.configure do |config|
-  config.test_mode = true
-end
 ```
 
-### Using Checker class
-
-```ruby
-require 'email_domain_checker'
-
-# Basic validation
-checker = EmailDomainChecker::Checker.new("user@example.com")
-if checker.valid?
-  puts "Valid email with valid domain"
-end
+## Documentation
 
-# Check format only
-checker = EmailDomainChecker::Checker.new("user@example.com", validate_domain: false)
-checker.format_valid? # => true
+📖 **[Full Documentation](https://tatematsu-k.github.io/email_domain_checker/latest/)** - Complete usage guide, API reference, and examples
 
-# Check domain with MX records
-checker = EmailDomainChecker::Checker.new("user@example.com", check_mx: true)
-checker.domain_valid? # => true if MX records exist
+## Features
 
-# Get normalized email
-checker = EmailDomainChecker::Checker.new("User@Example.COM")
-checker.normalized_email # => "user@example.com"
+- ✅ Email format validation
+- ✅ Domain existence validation
+- ✅ MX record checking
+- ✅ A record checking
+- ✅ Email normalization
+- ✅ ActiveModel/ActiveRecord integration
+- ✅ DNS result caching (memory and Redis)
+- ✅ Test mode for development
 
-# Get canonical email
-checker = EmailDomainChecker::Checker.new("user.name+tag@gmail.com")
-checker.canonical_email # => "username@gmail.com"
-
-# Get redacted email (for privacy)
-checker = EmailDomainChecker::Checker.new("user@example.com")
-checker.redacted_email # => "{hash}@example.com"
-```
-
-### ActiveModel/ActiveRecord Integration
-
-When ActiveModel is available, you can use the `DomainCheckValidator` for easy validation and normalization in your models:
-
-```ruby
-class User < ActiveRecord::Base
-  validates :email, domain_check: { check_mx: true, timeout: 3 }, normalize: true
-end
-```
-
-#### Options
-
-- `domain_check`: Hash of options for domain validation
-  - `check_mx`: Check MX records (default: `true`)
-  - `check_a`: Check A records (default: `false`)
-  - `timeout`: DNS query timeout in seconds (default: `5`)
-  - `validate_format`: Validate email format (default: `true`)
-  - `validate_domain`: Validate domain (default: `true`)
-- `normalize`: Normalize email before validation (default: `false`)
-- `message`: Custom error message
+## Development
 
-#### Examples
+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.
 
-```ruby
-# Basic validation with domain check
-class User < ActiveRecord::Base
-  validates :email, domain_check: { check_mx: true, timeout: 3 }
-end
-
-# Format validation only (skip domain check)
-class User < ActiveRecord::Base
-  validates :email, domain_check: { validate_domain: false }
-end
-
-# With automatic normalization
-class User < ActiveRecord::Base
-  validates :email, domain_check: { check_mx: true }, normalize: true
-end
-
-# With custom error message
-class User < ActiveRecord::Base
-  validates :email, domain_check: { check_mx: true }, message: "Invalid email address"
-end
-```
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
-### Configuration Options
+### Building Documentation Locally
 
-- `validate_format`: Validate email format using email_address gem (default: true)
-- `validate_domain`: Validate domain existence (default: true)
-- `check_mx`: Check MX records for domain (default: true)
-- `check_a`: Check A records for domain (default: false)
-- `timeout`: DNS lookup timeout in seconds (default: 5)
-- `test_mode`: Skip DNS checks (useful for testing with dummy data) (default: false)
+To build and preview the documentation locally:
 
-### Test Mode
+```bash
+# Install Python dependencies
+pip install -r requirements.txt
 
-When writing tests, you may want to skip DNS checks to avoid external requests. Enable test mode to skip all DNS validations (MX and A record checks):
+# Start development server (with live reload)
+mkdocs serve
 
-```ruby
-# In spec_helper.rb or test_helper.rb
-EmailDomainChecker.configure do |config|
-  config.test_mode = true
-end
-
-# Or in a before block
-before do
-  EmailDomainChecker::Config.test_mode = true
-end
+# Build static site
+mkdocs build
 ```
 
-When test mode is enabled, domain validation will always return `true` without making any DNS requests, allowing you to use dummy email addresses in your tests without external dependencies.
-
-## 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 the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+The documentation will be available at `http://127.0.0.1:8000` when using `mkdocs serve`. The built files will be in the `site/` directory when using `mkdocs build`.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/yourusername/email_domain_checker.
+Bug reports and pull requests are welcome on GitHub at https://github.com/tatematsu-k/email_domain_checker.
 
 ## License
 

data/docs/configuration/cache.md

@@ -0,0 +1,165 @@
+# Cache Configuration
+
+DNS validation results are cached by default using in-memory storage to improve performance when validating the same domains multiple times. The cache supports both in-memory storage (default) and Redis (optional).
+
+!!! note "Production Recommendation"
+    While memory cache is enabled by default and works well for development and small applications, we recommend using Redis cache in production environments for better scalability, persistence across application restarts, and shared cache across multiple application instances.
+
+## Memory Cache (Default - Enabled by Default)
+
+Cache is enabled by default - no configuration needed. Just use EmailDomainChecker normally and DNS results will be cached.
+
+### Customize Cache TTL
+
+```ruby
+EmailDomainChecker.configure do |config|
+  config.cache_ttl = 1800 # Cache entries expire after 30 minutes
+end
+```
+
+### Disable Cache
+
+```ruby
+EmailDomainChecker.configure do |config|
+  config.cache_enabled = false
+end
+```
+
+## Redis Cache (Recommended for Production)
+
+For production environments, Redis cache is recommended for the following reasons:
+
+- **Persistence**: Cache survives application restarts
+- **Scalability**: Shared cache across multiple application instances
+- **Performance**: Better memory management for large-scale applications
+- **Reliability**: Handles cache eviction and expiration more efficiently
+
+### Setup
+
+First, add the `redis` gem to your Gemfile:
+
+```ruby
+gem 'redis'
+```
+
+Then configure:
+
+```ruby
+# Enable Redis cache
+EmailDomainChecker.configure do |config|
+  config.cache_enabled = true
+  config.cache_type = :redis
+  config.cache_ttl = 3600
+  config.redis_client = Redis.new(url: "redis://localhost:6379")
+end
+```
+
+!!! tip "Fallback Behavior"
+    If Redis is not available, the gem will automatically fall back to memory cache.
+
+## Cache Management
+
+### Clear All Cache
+
+```ruby
+# Clear all cached DNS validation results
+EmailDomainChecker.clear_cache
+```
+
+### Clear Cache for Specific Domain
+
+```ruby
+# Clear cache for a specific domain
+EmailDomainChecker.clear_cache_for_domain("example.com")
+```
+
+### Cache Keys
+
+Cache keys are automatically managed by the gem:
+
+- MX records: `mx:example.com`
+- A records: `a:example.com`
+
+## Using `with` Method (Rails-style Cache Interface)
+
+The cache adapters support a Rails-like `with` method (similar to `Rails.cache.fetch`) for convenient cache access. Cache is enabled by default, so you can use it immediately:
+
+```ruby
+# Method 1: Direct access via EmailDomainChecker.cache (recommended)
+result = EmailDomainChecker.cache.with("my_key", ttl: 3600) do
+  # This block executes only when cache misses
+  expensive_computation
+end
+
+# Method 2: Using convenience method
+result = EmailDomainChecker.with_cache("my_key", ttl: 3600) do
+  expensive_computation
+end
+
+# Force cache refresh
+result = EmailDomainChecker.cache.with("my_key", force: true) do
+  # This block always executes
+  updated_computation
+end
+
+# Or using convenience method
+result = EmailDomainChecker.with_cache("my_key", force: true) do
+  updated_computation
+end
+```
+
+## Custom Cache Adapter
+
+You can implement your own cache adapter by inheriting from `EmailDomainChecker::Cache::BaseAdapter`:
+
+```ruby
+# Define a custom cache adapter
+class MyCustomCacheAdapter < EmailDomainChecker::Cache::BaseAdapter
+  def initialize
+    @store = {} # Your custom storage
+  end
+
+  def get(key)
+    # Your custom get logic
+    @store[key]
+  end
+
+  def set(key, value, ttl: nil)
+    # Your custom set logic
+    @store[key] = value
+  end
+
+  def delete(key)
+    # Your custom delete logic
+    @store.delete(key)
+  end
+
+  def clear
+    # Your custom clear logic
+    @store.clear
+  end
+end
+```
+
+### Using Custom Adapter Instance
+
+```ruby
+# Use custom adapter instance
+EmailDomainChecker.configure do |config|
+  config.cache_enabled = true
+  config.cache_adapter_instance = MyCustomCacheAdapter.new
+end
+```
+
+### Using Custom Adapter Class
+
+```ruby
+# Or use custom adapter class (will be instantiated automatically)
+EmailDomainChecker.configure do |config|
+  config.cache_enabled = true
+  config.cache_type = MyCustomCacheAdapter
+end
+```
+
+!!! note "Priority"
+    When both `cache_adapter_instance` and `cache_type` are set, the instance takes priority.

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
+