valid_email_checker 0.1.0

data/lib/valid_email_checker/configuration.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+module ValidEmailChecker
+  # Verification settings.
+  #
+  # Set process-wide defaults with {ValidEmailChecker.configure}, and override
+  # any of them per call by passing the same keys to {ValidEmailChecker.check}.
+  #
+  # Timeouts are expressed in seconds here, the way Ruby's own APIs do; they
+  # are converted to milliseconds on the way into Rust.
+  class Configuration
+    # Strategies the native extension understands, per provider.
+    YAHOO_METHODS = %i[api headless smtp].freeze
+    HOTMAIL_B2C_METHODS = %i[smtp headless].freeze
+
+    # Address used in the `MAIL FROM:` command. Upstream's default is an
+    # unused address owned by the Reacher project; set this to one you control,
+    # since some mail exchangers check it.
+    DEFAULT_FROM_EMAIL = "reacher@gmail.com"
+
+    # Name used in the `EHLO` command. Should be a domain you own, with
+    # matching forward and reverse DNS, or many servers will refuse to talk.
+    DEFAULT_HELLO_NAME = "gmail.com"
+
+    # Wall-clock ceiling for verifying one address. Upstream has no overall
+    # timeout; we default to one so a single unresponsive mail server cannot
+    # block a caller forever. Set to +nil+ to remove the ceiling.
+    DEFAULT_TIMEOUT = 30
+
+    # How many addresses {ValidEmailChecker.check_many} verifies at once.
+    DEFAULT_CONCURRENCY = 10
+
+    # Address used in the `MAIL FROM:` SMTP command.
+    attr_accessor :from_email
+    # Name used in the `EHLO` SMTP command.
+    attr_accessor :hello_name
+    # Port to connect to. Usually 25; try 587 or 2525 if 25 is blocked.
+    attr_accessor :smtp_port
+    # Timeout for one SMTP connection, in seconds. +nil+ for none.
+    attr_accessor :smtp_timeout
+    # Total number of SMTP connections to attempt. 2 can get past greylisting.
+    attr_accessor :retries
+    # Whether to look up a Gravatar for the address. Adds a HTTP round trip.
+    attr_accessor :check_gravatar
+    # API key enabling the HaveIBeenPwned breach lookup.
+    attr_accessor :haveibeenpwned_api_key
+    # SOCKS5 proxy, as a Hash of +:host+, +:port+ and optionally +:username+,
+    # +:password+, +:timeout+ (seconds).
+    attr_accessor :proxy
+    # WebDriver endpoint, used only by the +:headless+ strategies.
+    attr_accessor :webdriver_addr
+    # Identifier recorded in the result's debug section.
+    attr_accessor :backend_name
+    # Wall-clock ceiling per address, in seconds. +nil+ for none.
+    attr_accessor :timeout
+    # Strategy for Yahoo addresses: +:api+, +:headless+ or +:smtp+.
+    attr_accessor :yahoo
+    # Strategy for consumer Hotmail/Outlook addresses: +:smtp+ or +:headless+.
+    attr_accessor :hotmail_b2c
+    # Default concurrency for {ValidEmailChecker.check_many}.
+    attr_accessor :concurrency
+
+    # Keys accepted by {#initialize} and by per-call overrides.
+    KEYS = %i[
+      from_email hello_name smtp_port smtp_timeout retries check_gravatar
+      haveibeenpwned_api_key proxy webdriver_addr backend_name timeout
+      yahoo hotmail_b2c concurrency
+    ].freeze
+
+    def initialize(**overrides)
+      @from_email = DEFAULT_FROM_EMAIL
+      @hello_name = DEFAULT_HELLO_NAME
+      @smtp_port = 25
+      @smtp_timeout = nil
+      @retries = 1
+      @check_gravatar = false
+      @haveibeenpwned_api_key = nil
+      @proxy = nil
+      @webdriver_addr = nil
+      @backend_name = "valid_email_checker"
+      @timeout = DEFAULT_TIMEOUT
+      # Defaults that differ from upstream so the gem works out of the box with
+      # no WebDriver process running. Pass :headless to match upstream.
+      @yahoo = :api
+      @hotmail_b2c = :smtp
+      @concurrency = DEFAULT_CONCURRENCY
+
+      apply(overrides)
+    end
+
+    # A copy of this configuration with +overrides+ applied. Used for per-call
+    # options, so that a call never mutates the global configuration.
+    def merge(overrides)
+      return self if overrides.nil? || overrides.empty?
+
+      dup.tap { |config| config.send(:apply, overrides) }
+    end
+
+    def to_h
+      KEYS.to_h { |key| [key, public_send(key)] }
+    end
+
+    # The payload handed to the native extension.
+    #
+    # Deliberately excludes +concurrency+, which is a Ruby-side concern: the
+    # Rust options struct rejects unknown fields, which is what catches typos
+    # in caller-supplied option names.
+    def to_native_payload
+      validate!
+
+      {
+        from_email: from_email,
+        hello_name: hello_name,
+        smtp_port: smtp_port,
+        smtp_timeout_ms: seconds_to_ms(smtp_timeout),
+        retries: retries,
+        check_gravatar: check_gravatar,
+        haveibeenpwned_api_key: haveibeenpwned_api_key,
+        proxy: proxy_payload,
+        webdriver_addr: webdriver_addr,
+        backend_name: backend_name,
+        timeout_ms: seconds_to_ms(timeout),
+        yahoo: yahoo&.to_sym,
+        hotmail_b2c: hotmail_b2c&.to_sym
+      }
+    end
+
+    def validate!
+      unless yahoo.nil? || YAHOO_METHODS.include?(yahoo.to_sym)
+        raise ConfigurationError,
+              "yahoo must be one of #{YAHOO_METHODS.inspect}, got #{yahoo.inspect}"
+      end
+
+      unless hotmail_b2c.nil? || HOTMAIL_B2C_METHODS.include?(hotmail_b2c.to_sym)
+        raise ConfigurationError,
+              "hotmail_b2c must be one of #{HOTMAIL_B2C_METHODS.inspect}, got #{hotmail_b2c.inspect}"
+      end
+
+      if (yahoo&.to_sym == :headless || hotmail_b2c&.to_sym == :headless) && webdriver_addr.nil?
+        raise ConfigurationError,
+              "the :headless strategy needs a running WebDriver; set webdriver_addr " \
+              "(commonly \"http://localhost:9515\" for chromedriver)"
+      end
+
+      validate_proxy!
+
+      [[:timeout, timeout], [:smtp_timeout, smtp_timeout]].each do |name, value|
+        next if value.nil?
+        raise ConfigurationError, "#{name} must be positive, got #{value.inspect}" unless value.positive?
+      end
+
+      unless (1..65_535).cover?(smtp_port.to_i)
+        raise ConfigurationError, "smtp_port must be between 1 and 65535, got #{smtp_port.inspect}"
+      end
+
+      raise ConfigurationError, "retries must be at least 1, got #{retries.inspect}" if retries.to_i < 1
+
+      self
+    end
+
+    private
+
+    def apply(overrides)
+      overrides.each do |key, value|
+        unless KEYS.include?(key.to_sym)
+          raise ConfigurationError,
+                "unknown option #{key.inspect}; valid options are #{KEYS.inspect}"
+        end
+
+        public_send(:"#{key}=", value)
+      end
+
+      self
+    end
+
+    def validate_proxy!
+      return if proxy.nil?
+
+      unless proxy.respond_to?(:to_h)
+        raise ConfigurationError, "proxy must be a Hash of :host and :port, got #{proxy.inspect}"
+      end
+
+      hash = proxy.to_h
+      allowed = %i[host port username password timeout]
+      unknown = hash.keys.map(&:to_sym) - allowed
+      unless unknown.empty?
+        raise ConfigurationError, "unknown proxy keys #{unknown.inspect}; valid keys are #{allowed.inspect}"
+      end
+
+      host = hash[:host] || hash["host"]
+      port = hash[:port] || hash["port"]
+      raise ConfigurationError, "proxy requires a :host" if host.nil? || host.to_s.empty?
+      raise ConfigurationError, "proxy requires a :port" if port.nil?
+    end
+
+    def proxy_payload
+      return nil if proxy.nil?
+
+      hash = proxy.to_h.transform_keys(&:to_sym)
+
+      {
+        host: hash[:host].to_s,
+        port: hash[:port].to_i,
+        username: hash[:username],
+        password: hash[:password],
+        timeout_ms: seconds_to_ms(hash[:timeout])
+      }
+    end
+
+    def seconds_to_ms(seconds)
+      return nil if seconds.nil?
+
+      (Float(seconds) * 1000).round
+    end
+  end
+end

data/lib/valid_email_checker/errors.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ValidEmailChecker
+  # Base class for errors specific to this gem.
+  #
+  # Note that bad arguments raise Ruby's own ::ArgumentError rather than
+  # something under this namespace, so that a plain `rescue ArgumentError`
+  # behaves the way it does everywhere else.
+  class Error < StandardError; end
+
+  # Raised when options are not usable: an unknown provider strategy, a proxy
+  # missing a host, a non-positive timeout, and so on.
+  #
+  # Raised before any network access happens, so nothing has been sent when
+  # you see this.
+  class ConfigurationError < Error; end
+
+  # Raised on macOS when a process tries to verify an address after forking
+  # from a parent that had already verified one.
+  #
+  # Apple's Network.framework is not fork-safe. The first verification in a
+  # process initializes XPC and dispatch state for the system resolver, and a
+  # child inherits that state in a form it cannot use: its next connection
+  # attempt deadlocks inside the framework and never returns, not even when the
+  # configured timeout expires.
+  #
+  # We cannot repair the inherited state, so this is raised in place of a hang
+  # that would otherwise be indistinguishable from a very slow mail server.
+  # See the "Forking servers" section of the README for how to avoid it --
+  # in short, do not verify in a parent process before forking.
+  class ForkAfterVerificationError < Error; end
+end

data/lib/valid_email_checker/result.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+module ValidEmailChecker
+  # The outcome of verifying one address.
+  #
+  # This wraps the JSON document the embedded Rust crate produces. The
+  # predicate methods cover the questions callers usually have; anything not
+  # given a method is still reachable through {#to_h}, which holds the upstream
+  # structure verbatim under +:syntax+, +:mx+, +:smtp+, +:misc+ and +:debug+.
+  #
+  #   result = ValidEmailChecker.check("someone@gmail.com")
+  #   result.reachable     # => :safe
+  #   result.safe?         # => true
+  #   result.disposable?   # => false
+  #   result.to_h[:smtp]   # => {can_connect_smtp: true, ...}
+  class Result
+    # The four verdicts the crate can reach, in decreasing order of confidence
+    # that mail will arrive.
+    REACHABILITY = %i[safe risky invalid unknown].freeze
+
+    # @return [Hash] the raw upstream result, with symbol keys
+    attr_reader :to_h
+
+    def initialize(data)
+      @to_h = data.freeze
+    end
+
+    # @return [ValidEmailChecker::Result]
+    def self.from_json(json)
+      new(JSON.parse(json, symbolize_names: true))
+    end
+
+    # @return [String] the address that was checked, as it was given
+    def email
+      to_h[:input].to_s
+    end
+    alias input email
+
+    # How confident the crate is that mail sent here would arrive.
+    #
+    # @return [Symbol] +:safe+, +:risky+, +:invalid+ or +:unknown+
+    def reachable
+      value = to_h[:is_reachable]
+      value.nil? ? :unknown : value.to_sym
+    end
+
+    # Mail should arrive, and the address has no quality problems.
+    def safe?
+      reachable == :safe
+    end
+
+    # The address exists but is flagged: catch-all, disposable, role-based, or
+    # a full inbox. Mail may arrive, or may bounce.
+    def risky?
+      reachable == :risky
+    end
+
+    # The address does not exist or is malformed. Do not send here.
+    def invalid?
+      reachable == :invalid
+    end
+
+    # The mail server gave no usable answer. Common when port 25 is blocked
+    # outbound, the server greylists, or the IP is blacklisted -- check
+    # {#error} before concluding anything about the address.
+    def unknown?
+      reachable == :unknown
+    end
+
+    # Whether the address is safe to send to.
+    #
+    # This is deliberately strict: only +:safe+ counts. Treating +:risky+ or
+    # +:unknown+ as usable is a policy decision, so make it explicitly with
+    # {#reachable} rather than relying on a looser default here.
+    def valid?
+      safe?
+    end
+
+    # @return [ValidEmailChecker::Syntax]
+    def syntax
+      @syntax ||= Syntax.new(to_h[:syntax])
+    end
+
+    # --- SMTP findings -------------------------------------------------------
+
+    # @return [Boolean] the mail exchanger accepted the recipient
+    def deliverable?
+      smtp[:is_deliverable] == true
+    end
+
+    # @return [Boolean] we completed an SMTP conversation with the server
+    def can_connect_smtp?
+      smtp[:can_connect_smtp] == true
+    end
+
+    # @return [Boolean] the domain accepts mail for every address, so an
+    #   individual address cannot be confirmed to exist
+    def catch_all?
+      smtp[:is_catch_all] == true
+    end
+
+    # @return [Boolean] the mailbox is over quota
+    def full_inbox?
+      smtp[:has_full_inbox] == true
+    end
+
+    # @return [Boolean] the provider has blocked or deactivated the mailbox
+    def disabled?
+      smtp[:is_disabled] == true
+    end
+
+    # --- Domain and address metadata ----------------------------------------
+
+    # @return [Boolean] the domain has MX records
+    def accepts_mail?
+      mx[:accepts_mail] == true
+    end
+
+    # @return [Array<String>] the mail exchangers found for the domain
+    def mx_records
+      Array(mx[:records])
+    end
+
+    # @return [Boolean] the address belongs to a known throwaway-mail provider
+    def disposable?
+      misc[:is_disposable] == true
+    end
+
+    # @return [Boolean] the address is a shared mailbox such as info@ or
+    #   support@, rather than a person
+    def role_account?
+      misc[:is_role_account] == true
+    end
+
+    # @return [Boolean] the address is a consumer rather than a business one
+    def b2c?
+      misc[:is_b2c] == true
+    end
+
+    # @return [String, nil] the Gravatar image URL, when +check_gravatar+ was
+    #   enabled and one exists
+    def gravatar_url
+      misc[:gravatar_url]
+    end
+
+    # Whether the address appears in a HaveIBeenPwned breach.
+    #
+    # @return [Boolean, nil] nil when no +haveibeenpwned_api_key+ was set, so
+    #   the lookup never ran
+    def pwned?
+      misc[:haveibeenpwned]
+    end
+
+    # --- Errors and timing ---------------------------------------------------
+
+    # The reason a stage could not complete, if any.
+    #
+    # Present mainly on +:unknown+ results. The +:type+ is the upstream error
+    # variant, or +"Timeout"+ when the call hit its wall-clock budget.
+    #
+    # @return [Hash, nil] with +:type+ and +:message+ keys
+    def error
+      to_h[:error] || smtp_error || mx_error || misc_error
+    end
+
+    # @return [Boolean] whether anything went wrong during verification
+    def error?
+      !error.nil?
+    end
+
+    # @return [Boolean] whether the wall-clock budget ran out. The address was
+    #   neither confirmed nor rejected; retrying later may succeed.
+    def timed_out?
+      error&.dig(:type).to_s == "Timeout"
+    end
+
+    # A hint about a recoverable cause of an +:unknown+ result, such as the
+    # sending IP being blacklisted or lacking a reverse DNS record.
+    #
+    # @return [String, nil]
+    def error_description
+      to_h.dig(:smtp, :description)
+    end
+
+    # @return [Float, nil] how long verification took, in seconds
+    def duration
+      value = to_h.dig(:debug, :duration)
+      return nil if value.nil?
+
+      value[:secs].to_i + (value[:nanos].to_i / 1_000_000_000.0)
+    end
+
+    # --- Plumbing ------------------------------------------------------------
+
+    def [](key)
+      to_h[key.to_sym]
+    end
+
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+
+    def inspect
+      "#<#{self.class} #{email.inspect} #{reachable}#{error? ? " error=#{error[:type].inspect}" : ""}>"
+    end
+
+    private
+
+    # The upstream result replaces a section with +{error: ...}+ when that
+    # stage failed, so every reader has to tolerate the section being an error
+    # rather than the details it normally holds.
+    def section(name)
+      value = to_h[name]
+      value.is_a?(Hash) && !value.key?(:error) ? value : {}
+    end
+
+    def smtp
+      section(:smtp)
+    end
+
+    def mx
+      section(:mx)
+    end
+
+    def misc
+      section(:misc)
+    end
+
+    def smtp_error
+      to_h.dig(:smtp, :error)
+    end
+
+    def mx_error
+      to_h.dig(:mx, :error)
+    end
+
+    def misc_error
+      to_h.dig(:misc, :error)
+    end
+  end
+end

data/lib/valid_email_checker/syntax.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module ValidEmailChecker
+  # The outcome of parsing an address, with no network access involved.
+  #
+  # Returned on its own by {ValidEmailChecker.syntax}, and reachable as
+  # {Result#syntax} after a full verification.
+  class Syntax
+    # @return [Hash] the raw data as the Rust crate reported it
+    attr_reader :to_h
+
+    def initialize(data)
+      @to_h = (data || {}).freeze
+    end
+
+    # @return [Boolean] whether the address parses as a well-formed address
+    def valid?
+      to_h[:is_valid_syntax] == true
+    end
+
+    # @return [String, nil] the address, or nil if it did not parse
+    def address
+      to_h[:address]
+    end
+
+    # @return [String] the part before the "@", or "" for an unparseable address
+    def username
+      to_h[:username].to_s
+    end
+
+    # @return [String] the part after the "@", or "" for an unparseable address
+    def domain
+      to_h[:domain].to_s
+    end
+
+    # @return [String, nil] the address with provider-specific quirks removed,
+    #   such as Gmail's dots and "+" tags
+    def normalized_email
+      to_h[:normalized_email]
+    end
+
+    # A likely correction when the domain looks like a typo of a well-known
+    # provider, e.g. "gmail.co" -> "gmail.com".
+    #
+    # Only offered for an address that parses: notorious typo domains such as
+    # "gmial.com" are on upstream's blocklist, so they come back invalid with
+    # no domain to compare against and hence no suggestion.
+    #
+    # @return [String, nil]
+    def suggestion
+      to_h[:suggestion]
+    end
+
+    # @return [Boolean] whether a likely typo correction is available
+    def suggestion?
+      !suggestion.nil?
+    end
+
+    def [](key)
+      to_h[key.to_sym]
+    end
+
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+
+    def inspect
+      "#<#{self.class} #{address.inspect} valid=#{valid?}" \
+        "#{suggestion? ? " suggestion=#{suggestion.inspect}" : ""}>"
+    end
+  end
+end

data/lib/valid_email_checker/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ValidEmailChecker
+  VERSION = "0.1.0"
+end