RubyGems - email_domain_checker - Versions diffs - 0.1.2 → 0.1.3 - Mend

email_domain_checker 0.1.2 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (26) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +10 -0
data/README.md +27 -112
data/docs/configuration/cache.md +165 -0
data/docs/configuration/options.md +68 -0
data/docs/configuration/test-mode.md +40 -0
data/docs/contributing.md +9 -0
data/docs/getting-started/installation.md +28 -0
data/docs/getting-started/quick-start.md +47 -0
data/docs/index.md +37 -0
data/docs/usage/activemodel-integration.md +68 -0
data/docs/usage/checker-class.md +60 -0
data/docs/usage/module-methods.md +95 -0
data/docs-templates/index.html +71 -0
data/lib/email_domain_checker/cache/base_adapter.rb +67 -0
data/lib/email_domain_checker/cache/memory_adapter.rb +91 -0
data/lib/email_domain_checker/cache/redis_adapter.rb +66 -0
data/lib/email_domain_checker/cache.rb +54 -0
data/lib/email_domain_checker/config.rb +116 -2
data/lib/email_domain_checker/dns_resolver.rb +26 -3
data/lib/email_domain_checker/domain_validator.rb +2 -1
data/lib/email_domain_checker/version.rb +1 -1
data/lib/email_domain_checker.rb +32 -0
data/mkdocs.yml +65 -0
data/requirements.txt +2 -0
metadata +18 -1

data/docs/usage/checker-class.md ADDED Viewed

@@ -0,0 +1,60 @@
+# Using Checker Class
+The `EmailDomainChecker::Checker` class provides a more object-oriented approach to email validation.
+## Basic Usage
+```ruby
+require 'email_domain_checker'
+# Basic validation
+checker = EmailDomainChecker::Checker.new("user@example.com")
+if checker.valid?
+  puts "Valid email with valid domain"
+end
+```
+## Validation Methods
+### Format Validation Only
+```ruby
+checker = EmailDomainChecker::Checker.new("user@example.com", validate_domain: false)
+checker.format_valid? # => true
+```
+### Domain Validation with MX Records
+```ruby
+checker = EmailDomainChecker::Checker.new("user@example.com", check_mx: true)
+checker.domain_valid? # => true if MX records exist
+```
+## Email Transformations
+### Normalized Email
+Get the normalized (lowercase) version of the email:
+```ruby
+checker = EmailDomainChecker::Checker.new("User@Example.COM")
+checker.normalized_email # => "user@example.com"
+```
+### Canonical Email
+Get the canonical version of the email (handles Gmail-style aliases):
+```ruby
+checker = EmailDomainChecker::Checker.new("user.name+tag@gmail.com")
+checker.canonical_email # => "username@gmail.com"
+```
+### Redacted Email
+Get a redacted version of the email for privacy (shows hash instead of local part):
+```ruby
+checker = EmailDomainChecker::Checker.new("user@example.com")
+checker.redacted_email # => "{hash}@example.com"
+```

data/docs/usage/module-methods.md ADDED Viewed

@@ -0,0 +1,95 @@
+# Module-level Convenience Methods
+The `EmailDomainChecker` module provides convenient class methods for quick validation and configuration.
+## Validation Methods
+### `valid?`
+Quick validation with optional domain checking:
+```ruby
+EmailDomainChecker.valid?("user@example.com", validate_domain: false) # => true
+EmailDomainChecker.valid?("user@example.com", check_mx: true) # => true/false
+```
+### `format_valid?`
+Validate email format only (skips domain validation):
+```ruby
+EmailDomainChecker.format_valid?("user@example.com") # => true
+EmailDomainChecker.format_valid?("invalid-email") # => false
+```
+### `domain_valid?`
+Validate domain only (skips format validation):
+```ruby
+EmailDomainChecker.domain_valid?("user@example.com", check_mx: true) # => true/false
+EmailDomainChecker.domain_valid?("user@nonexistent.com", check_mx: true) # => false
+```
+## Utility Methods
+### `normalize`
+Normalize email address to lowercase:
+```ruby
+EmailDomainChecker.normalize("User@Example.COM") # => "user@example.com"
+```
+## Configuration
+### Global Configuration
+```ruby
+EmailDomainChecker.configure(timeout: 10, check_mx: true)
+```
+### Block Configuration
+```ruby
+EmailDomainChecker.configure do |config|
+  config.test_mode = true
+  config.cache_ttl = 3600
+  config.cache_enabled = true
+end
+```
+## Cache Management
+### Clear All Cache
+```ruby
+EmailDomainChecker.clear_cache
+```
+### Clear Cache for Specific Domain
+```ruby
+EmailDomainChecker.clear_cache_for_domain("example.com")
+```
+### Using Cache with Blocks
+```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.with_cache("my_key", force: true) do
+  # This block always executes
+  updated_computation
+end
+```

data/docs-templates/index.html ADDED Viewed

@@ -0,0 +1,71 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>EmailDomainChecker Documentation</title>
+    <style>
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
+            max-width: 800px;
+            margin: 0 auto;
+            padding: 2rem;
+            background: #f5f5f5;
+        }
+        .container {
+            background: white;
+            border-radius: 8px;
+            padding: 2rem;
+            box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+        }
+        h1 {
+            color: #333;
+            margin-bottom: 0.5rem;
+        }
+        .subtitle {
+            color: #666;
+            margin-bottom: 2rem;
+        }
+        .versions {
+            list-style: none;
+            padding: 0;
+        }
+        .versions li {
+            margin: 0.5rem 0;
+        }
+        .versions a {
+            display: inline-block;
+            padding: 0.75rem 1.5rem;
+            background: #6200ea;
+            color: white;
+            text-decoration: none;
+            border-radius: 4px;
+            transition: background 0.2s;
+        }
+        .versions a:hover {
+            background: #7c3aed;
+        }
+        .version-label {
+            font-weight: 600;
+            margin-right: 0.5rem;
+        }
+        .latest-badge {
+            background: #4caf50;
+            color: white;
+            padding: 0.2rem 0.5rem;
+            border-radius: 3px;
+            font-size: 0.8rem;
+            margin-left: 0.5rem;
+        }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <h1>EmailDomainChecker Documentation</h1>
+        <p class="subtitle">Select a version to view documentation</p>
+        <ul class="versions">
+            {{VERSION_LIST}}
+        </ul>
+    </div>
+</body>
+</html>

data/lib/email_domain_checker/cache/base_adapter.rb ADDED Viewed

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+module EmailDomainChecker
+  module Cache
+    # Base class for cache adapters
+    # All cache adapters must implement these methods
+    class BaseAdapter
+      # Get cached value for a key
+      # @param key [String] cache key
+      # @return [Object, nil] cached value or nil if not found
+      def get(key)
+        raise NotImplementedError, "Subclasses must implement #get"
+      end
+      # Set a value in cache
+      # @param key [String] cache key
+      # @param value [Object] value to cache
+      # @param ttl [Integer, nil] time to live in seconds (nil for no expiration)
+      # @return [void]
+      def set(key, value, ttl: nil)
+        raise NotImplementedError, "Subclasses must implement #set"
+      end
+      # Delete a key from cache
+      # @param key [String] cache key
+      # @return [void]
+      def delete(key)
+        raise NotImplementedError, "Subclasses must implement #delete"
+      end
+      # Clear all cache entries
+      # @return [void]
+      def clear
+        raise NotImplementedError, "Subclasses must implement #clear"
+      end
+      # Check if a key exists in cache
+      # @param key [String] cache key
+      # @return [Boolean] true if key exists
+      def exists?(key)
+        get(key) != nil
+      end
+      # Fetch value from cache or execute block and cache the result
+      # Similar to Rails.cache.fetch
+      # @param key [String] cache key
+      # @param ttl [Integer, nil] time to live in seconds (nil for no expiration)
+      # @param force [Boolean] if true, always execute block and update cache
+      # @yield Block to execute when cache miss
+      # @return [Object] cached value or block result
+      def with(key, ttl: nil, force: false, &block)
+        raise ArgumentError, "Block is required" unless block_given?
+        # Return cached value if not forcing and cache exists
+        unless force
+          return get(key) if exists?(key)
+        end
+        # Execute block and cache the result
+        # Rails.cache.fetch also caches nil values, so we do the same
+        value = yield
+        set(key, value, ttl: ttl)
+        value
+      end
+    end
+  end
+end

data/lib/email_domain_checker/cache/memory_adapter.rb ADDED Viewed

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+require_relative "base_adapter"
+module EmailDomainChecker
+  module Cache
+    # In-memory cache adapter using a simple hash
+    # This is the default cache adapter when Redis is not available
+    class MemoryAdapter < BaseAdapter
+      def initialize
+        @store = {}
+        @expirations = {}
+        @nil_keys = {} # Track keys that have nil values
+      end
+      def get(key)
+        # Check if key exists (including nil values)
+        return nil unless @store.key?(key) || @nil_keys.key?(key)
+        # Check if expired
+        if @expirations.key?(key) && Time.now > @expirations[key]
+          delete(key)
+          return nil
+        end
+        # Return nil if it was explicitly cached, otherwise return stored value
+        return nil if @nil_keys.key?(key)
+        @store[key]
+      end
+      def set(key, value, ttl: nil)
+        if value.nil?
+          # Store nil separately to distinguish from "not cached"
+          @nil_keys[key] = true
+          @store.delete(key)
+        else
+          @store[key] = value
+          @nil_keys.delete(key)
+        end
+        if ttl
+          @expirations[key] = Time.now + ttl
+        else
+          @expirations.delete(key)
+        end
+        value
+      end
+      def delete(key)
+        @store.delete(key)
+        @nil_keys.delete(key)
+        @expirations.delete(key)
+      end
+      def clear
+        @store.clear
+        @nil_keys.clear
+        @expirations.clear
+      end
+      def exists?(key)
+        return false unless @store.key?(key) || @nil_keys.key?(key)
+        # Check if expired
+        if @expirations.key?(key) && Time.now > @expirations[key]
+          delete(key)
+          return false
+        end
+        true
+      end
+      # Get cache size (for debugging/monitoring)
+      def size
+        # Clean expired entries first
+        clean_expired
+        @store.size + @nil_keys.size
+      end
+      private
+      def clean_expired
+        now = Time.now
+        @expirations.each do |key, expiration|
+          delete(key) if now > expiration
+        end
+      end
+    end
+  end
+end

data/lib/email_domain_checker/cache/redis_adapter.rb ADDED Viewed

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+require_relative "base_adapter"
+module EmailDomainChecker
+  module Cache
+    # Redis cache adapter
+    # Requires the 'redis' gem to be available
+    class RedisAdapter < BaseAdapter
+      def initialize(redis_client = nil)
+        @redis = redis_client || create_default_redis_client
+      end
+      def get(key)
+        value = @redis.get(key)
+        return nil unless value
+        # Parse JSON value
+        JSON.parse(value)
+      rescue JSON::ParserError, Redis::BaseError
+        nil
+      end
+      def set(key, value, ttl: nil)
+        json_value = JSON.generate(value)
+        if ttl
+          @redis.setex(key, ttl, json_value)
+        else
+          @redis.set(key, json_value)
+        end
+        value
+      rescue Redis::BaseError
+        # Silently fail if Redis is unavailable
+        value
+      end
+      def delete(key)
+        @redis.del(key)
+      rescue Redis::BaseError
+        # Silently fail if Redis is unavailable
+      end
+      def clear
+        @redis.flushdb
+      rescue Redis::BaseError
+        # Silently fail if Redis is unavailable
+      end
+      def exists?(key)
+        @redis.exists?(key)
+      rescue Redis::BaseError
+        false
+      end
+      private
+      def create_default_redis_client
+        require "redis"
+        require "json"
+        Redis.new
+      rescue LoadError
+        raise LoadError, "Redis gem is required for RedisAdapter. Please add 'gem \"redis\"' to your Gemfile."
+      end
+    end
+  end
+end

data/lib/email_domain_checker/cache.rb ADDED Viewed

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+require_relative "cache/base_adapter"
+require_relative "cache/memory_adapter"
+# Conditionally load Redis adapter if available
+begin
+  require "redis"
+  require "json"
+  require_relative "cache/redis_adapter"
+rescue LoadError
+  # Redis is not available, skip Redis adapter
+end
+module EmailDomainChecker
+  module Cache
+    # Factory method to create cache adapter based on configuration
+    #
+    # @param type [Symbol, Class, Object] Cache adapter type, class, or instance
+    #   - Symbol: :memory or :redis
+    #   - Class: A custom adapter class (must inherit from BaseAdapter)
+    #   - Object: A custom adapter instance (must be an instance of BaseAdapter)
+    # @param redis_client [Redis, nil] Redis client instance (only used for :redis type)
+    # @return [BaseAdapter] Cache adapter instance
+    def self.create_adapter(type: :memory, redis_client: nil)
+      # If type is already an adapter instance, return it
+      return type if type.is_a?(BaseAdapter)
+      # If type is a Class, instantiate it
+      if type.is_a?(Class)
+        unless type < BaseAdapter
+          raise ArgumentError, "Custom cache adapter class must inherit from EmailDomainChecker::Cache::BaseAdapter"
+        end
+        return type.new
+      end
+      # Handle symbol types
+      case type.to_sym
+      when :memory
+        MemoryAdapter.new
+      when :redis
+        if defined?(RedisAdapter)
+          RedisAdapter.new(redis_client)
+        else
+          # Fallback to memory if Redis is not available
+          warn "Redis adapter requested but 'redis' gem is not available. Falling back to memory cache."
+          MemoryAdapter.new
+        end
+      else
+        raise ArgumentError, "Unknown cache adapter type: #{type}. Available: :memory, :redis, or a custom BaseAdapter class/instance"
+      end
+    end
+  end
+end

data/lib/email_domain_checker/config.rb CHANGED Viewed

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
+require_relative "cache"
 module EmailDomainChecker
   class Config
     DEFAULT_OPTIONS = {
@@ -11,7 +13,7 @@ module EmailDomainChecker
     }.freeze
     class << self
-      attr_accessor :default_options, :test_mode
+      attr_accessor :default_options, :test_mode, :cache_enabled, :cache_type, :cache_ttl, :cache_adapter, :cache_adapter_instance, :redis_client
       def configure(options = {}, &block)
         if block_given?
@@ -28,6 +30,12 @@ module EmailDomainChecker
       def reset
         @default_options = DEFAULT_OPTIONS.dup
         @test_mode = false
+        @cache_enabled = true
+        @cache_type = :memory
+        @cache_ttl = 3600
+        @cache_adapter = nil
+        @cache_adapter_instance = nil
+        @redis_client = nil
       end
       def test_mode=(value)
@@ -37,12 +45,86 @@ module EmailDomainChecker
       def test_mode?
         @test_mode == true
       end
+      def cache_enabled?
+        @cache_enabled == true
+      end
+      def cache_adapter
+        return nil unless cache_enabled?
+        # If custom adapter instance is set, use it directly
+        return @cache_adapter_instance if @cache_adapter_instance
+        # Otherwise, create adapter from type
+        @cache_adapter ||= Cache.create_adapter(type: cache_type, redis_client: redis_client)
+      end
+      def cache_adapter_instance=(instance)
+        validate_cache_adapter_instance!(instance)
+        @cache_adapter_instance = instance
+        # Reset the auto-created adapter when custom instance is set
+        @cache_adapter = nil
+      end
+      def cache_type=(value)
+        @cache_type = value
+        reset_cache_adapter_if_needed
+      end
+      def clear_cache
+        cache_adapter&.clear
+      end
+      def clear_cache_for_domain(domain)
+        return unless cache_enabled?
+        adapter = cache_adapter
+        return unless adapter
+        # Clear both MX and A record cache entries
+        dns_cache_keys_for_domain(domain).each do |key|
+          adapter.delete(key)
+        end
+      end
+      def reset_cache_adapter_if_needed
+        # Reset cache adapter when changing cache type (unless custom instance is set)
+        @cache_adapter = nil unless @cache_adapter_instance
+        # Clear cache_adapter_instance if setting a type (Symbol or String), not a Class
+        @cache_adapter_instance = nil if @cache_type.is_a?(Symbol) || @cache_type.is_a?(String)
+      end
+      def reset_cache_adapter_on_enabled_change(new_value, old_value)
+        @cache_adapter = nil if new_value != old_value
+      end
+      def reset_cache_adapter_if_redis
+        @cache_adapter = nil if @cache_type == :redis
+      end
+      def validate_cache_adapter_instance!(instance)
+        unless instance.nil? || instance.is_a?(Cache::BaseAdapter)
+          raise ArgumentError, "cache_adapter_instance must be an instance of EmailDomainChecker::Cache::BaseAdapter or nil"
+        end
+      end
+      private
+      def dns_cache_keys_for_domain(domain)
+        ["mx:#{domain}", "a:#{domain}"]
+      end
     end
-    attr_accessor :test_mode
+    attr_accessor :test_mode, :cache_enabled, :cache_type, :cache_ttl, :cache_adapter_instance, :redis_client
     def initialize
       @test_mode = self.class.test_mode || false
+      @cache_enabled = self.class.cache_enabled.nil? ? true : self.class.cache_enabled
+      @cache_type = self.class.cache_type || :memory
+      @cache_ttl = self.class.cache_ttl || 3600
+      @cache_adapter_instance = self.class.cache_adapter_instance
+      @redis_client = self.class.redis_client
     end
     def test_mode=(value)
@@ -50,6 +132,38 @@ module EmailDomainChecker
       self.class.test_mode = value
     end
+    def cache_enabled=(value)
+      old_value = self.class.cache_enabled
+      @cache_enabled = value
+      self.class.cache_enabled = value
+      # Reset cache adapter when enabling/disabling cache
+      self.class.reset_cache_adapter_on_enabled_change(value, old_value)
+    end
+    def cache_type=(value)
+      @cache_type = value
+      self.class.cache_type = value
+      self.class.reset_cache_adapter_if_needed
+    end
+    def cache_adapter_instance=(instance)
+      self.class.validate_cache_adapter_instance!(instance)
+      @cache_adapter_instance = instance
+      self.class.cache_adapter_instance = instance
+    end
+    def cache_ttl=(value)
+      @cache_ttl = value
+      self.class.cache_ttl = value
+    end
+    def redis_client=(value)
+      @redis_client = value
+      self.class.redis_client = value
+      # Reset cache adapter when changing redis client
+      self.class.reset_cache_adapter_if_redis
+    end
     reset
   end
 end