email_domain_checker 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9482f21ae74333979292271bf830aa22164a859388ba73b29a090118185ac797
-  data.tar.gz: 12fa14a045d73af82ff4d179c55d9f7c425ec25a1bc171d3328e60f5045f92de
+  metadata.gz: 16e187af255690a6a15e34fdfd3d034443ae6d335781f1b499ec0c100da6731b
+  data.tar.gz: 790adc384696330eadd419fed2cb46ff23fe0f874b59a28d7b74afc0a0bdb37b
 SHA512:
-  metadata.gz: ab00a7b94993e50f3e5e8c4b7d7fa74c270a77778c4bd7c5796f84420fe1ffb0c929ec3efa4999d573ba38325e431cca20359e55dcfe68d4b73f67367f57a92d
-  data.tar.gz: 7a1f651e88f540389f8d213e381a37047c96370d3ff2bb1b4bd8a3655045ac9bb9cf749695ca8c774d2cca38050028e11468f181c883ff6b391abaf57f1d544a
+  metadata.gz: fbd0732d8fccc016ca9ff9d302abcdc8e19f8fe2cbf392f671bb726306727cee4f5b0d2393f38736a6f9d1d4ed4db42359df667579eb6f7116d1691723b09115
+  data.tar.gz: 45cf7b78d7a22cafca5e1b236ea66426c375345acebc48b389d2230fda733d5a353a5e4cb72a18de17cc6bf6f8b21ee5ad532becd3566d010c514fbb262608f8

data/CHANGELOG.md

@@ -5,6 +5,16 @@ 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.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/options.md

@@ -0,0 +1,68 @@
+# Configuration Options
+
+EmailDomainChecker supports various configuration options to customize its behavior.
+
+## Available Options
+
+### Validation Options
+
+- `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
+
+- `test_mode`: Skip DNS checks (useful for testing with dummy data) (default: `false`)
+
+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.
+
+### Cache Options
+
+- `cache_enabled`: Enable/disable DNS validation result caching (default: `true` - memory cache is enabled by default)
+- `cache_type`: Cache adapter type (`:memory`, `:redis`, or a custom `BaseAdapter` class) (default: `:memory`)
+- `cache_adapter_instance`: Custom cache adapter instance (must inherit from `Cache::BaseAdapter`)
+- `cache_ttl`: Cache time-to-live in seconds (default: `3600`)
+- `redis_client`: Custom Redis client instance (only used when `cache_type` is `:redis`)
+
+## Configuration Examples
+
+### Basic Configuration
+
+```ruby
+EmailDomainChecker.configure(timeout: 10, check_mx: true)
+```
+
+### Block Configuration
+
+```ruby
+EmailDomainChecker.configure do |config|
+  config.timeout = 10
+  config.check_mx = true
+  config.check_a = false
+  config.cache_ttl = 1800
+end
+```
+
+### Test Mode Configuration
+
+```ruby
+EmailDomainChecker.configure do |config|
+  config.test_mode = true
+end
+```
+
+### Cache Configuration
+
+```ruby
+EmailDomainChecker.configure do |config|
+  config.cache_enabled = true
+  config.cache_type = :memory
+  config.cache_ttl = 3600
+end
+```
+
+## Note on Cache Adapter Priority
+
+When both `cache_adapter_instance` and `cache_type` are set, the instance takes priority.

data/docs/configuration/test-mode.md

@@ -0,0 +1,40 @@
+# Test Mode
+
+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).
+
+## Enabling Test Mode
+
+### In spec_helper.rb or test_helper.rb
+
+```ruby
+EmailDomainChecker.configure do |config|
+  config.test_mode = true
+end
+```
+
+### In a before block
+
+```ruby
+before do
+  EmailDomainChecker::Config.test_mode = true
+end
+```
+
+## Behavior
+
+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.
+
+## Example
+
+```ruby
+# In spec_helper.rb
+EmailDomainChecker.configure do |config|
+  config.test_mode = true
+end
+
+# In your specs
+it "validates email format" do
+  expect(EmailDomainChecker.valid?("test@example.com")).to be true
+  # Domain validation is skipped, but format validation still works
+end
+```

data/docs/contributing.md

@@ -0,0 +1,9 @@
+# Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/tatematsu-k/email_domain_checker.
+
+## 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).

data/docs/getting-started/installation.md

@@ -0,0 +1,28 @@
+# Installation
+
+## Using Bundler
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'email_domain_checker'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+## Manual Installation
+
+Or install it yourself as:
+
+```bash
+$ gem install email_domain_checker
+```
+
+## Requirements
+
+- Ruby 3.0 or higher
+- Optional: `redis` gem for Redis cache support

data/docs/getting-started/quick-start.md

@@ -0,0 +1,47 @@
+# Quick Start
+
+## Basic Usage
+
+```ruby
+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
+EmailDomainChecker.domain_valid?("user@example.com", check_mx: true) # => true/false
+
+# Normalize email
+EmailDomainChecker.normalize("User@Example.COM") # => "user@example.com"
+```
+
+## Configure Default Options
+
+```ruby
+# 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
+```
+
+## Cache Configuration
+
+Cache is enabled by default (memory cache):
+
+```ruby
+# Cache is enabled by default - no configuration needed
+# Just use EmailDomainChecker normally and DNS results will be cached
+
+# Customize cache TTL if needed
+EmailDomainChecker.configure do |config|
+  config.cache_ttl = 1800 # Cache entries expire after 30 minutes
+end
+```
+
+For production environments, Redis cache is recommended. See [Cache Configuration](../configuration/cache.md) for details.

data/docs/index.md

@@ -0,0 +1,37 @@
+# EmailDomainChecker
+
+Email address validation and domain checking library to prevent mail server reputation degradation.
+
+## Features
+
+- ✅ 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
+
+## Quick Example
+
+```ruby
+require 'email_domain_checker'
+
+# Quick validation
+EmailDomainChecker.valid?("user@example.com", validate_domain: false) # => true
+
+# 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"
+```
+
+## Documentation
+
+Please see the [Getting Started](getting-started/installation.md) guide for installation and setup instructions.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/docs/usage/activemodel-integration.md

@@ -0,0 +1,68 @@
+# ActiveModel/ActiveRecord Integration
+
+When ActiveModel is available, you can use the `DomainCheckValidator` for easy validation and normalization in your models.
+
+## Basic Usage
+
+```ruby
+class User < ActiveRecord::Base
+  validates :email, domain_check: { check_mx: true, timeout: 3 }, normalize: true
+end
+```
+
+## Validator Options
+
+### `domain_check` Options
+
+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`)
+
+### Other Options
+
+- `normalize`: Normalize email before validation (default: `false`)
+- `message`: Custom error message
+
+## Examples
+
+### Basic Validation with Domain Check
+
+```ruby
+class User < ActiveRecord::Base
+  validates :email, domain_check: { check_mx: true, timeout: 3 }
+end
+```
+
+### Format Validation Only
+
+Skip domain check and only validate format:
+
+```ruby
+class User < ActiveRecord::Base
+  validates :email, domain_check: { validate_domain: false }
+end
+```
+
+### With Automatic Normalization
+
+Automatically normalize email addresses before validation:
+
+```ruby
+class User < ActiveRecord::Base
+  validates :email, domain_check: { check_mx: true }, normalize: true
+end
+```
+
+### With Custom Error Message
+
+Provide a custom error message:
+
+```ruby
+class User < ActiveRecord::Base
+  validates :email, domain_check: { check_mx: true }, message: "Invalid email address"
+end
+```