valid_email_checker 0.1.0

data/lib/valid_email_checker.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "valid_email_checker/version"
+require_relative "valid_email_checker/errors"
+require_relative "valid_email_checker/configuration"
+require_relative "valid_email_checker/syntax"
+require_relative "valid_email_checker/result"
+
+# The compiled extension. rake-compiler installs a per-version copy when
+# several Ruby ABIs share a checkout, so prefer that when it is present.
+begin
+  ruby_abi = RUBY_VERSION[/\d+\.\d+/]
+  require_relative "valid_email_checker/#{ruby_abi}/valid_email_checker"
+rescue LoadError
+  require_relative "valid_email_checker/valid_email_checker"
+end
+
+# Check whether an email address really exists, without sending mail.
+#
+# This gem embeds the Rust crate
+# {https://github.com/reacherhq/check-if-email-exists check-if-email-exists}
+# and calls it in-process. A full check validates the syntax, resolves the
+# domain's MX records, opens an SMTP conversation with the mail exchanger and
+# asks about the recipient without ever completing a message, then reports
+# whether the address is disposable, role-based or catch-all.
+#
+#   ValidEmailChecker.check("someone@gmail.com").safe?   # => true
+#
+# == A note on what "exists" can mean
+#
+# SMTP verification is a best-effort signal, not a guarantee. Results come back
+# as +:unknown+ more often than people expect, for reasons that have nothing to
+# do with the address:
+#
+# * Most residential and cloud networks block outbound port 25. Without a
+#   SOCKS5 +proxy+, or a host that permits port 25, expect +:unknown+.
+# * Mail exchangers rate-limit, greylist and blacklist aggressively. A server
+#   you are unknown to may simply refuse to answer.
+# * Catch-all domains accept every recipient, so an individual address there
+#   can never be confirmed. Those come back +:risky+.
+#
+# Set +from_email+ and +hello_name+ to a domain you actually control, with
+# matching forward and reverse DNS, for markedly better results.
+module ValidEmailChecker
+  # Whether this platform's network stack deadlocks when a process verifies an
+  # address after forking from a parent that already had.
+  #
+  # True on macOS, whose Network.framework is not fork-safe. See
+  # {ForkAfterVerificationError} and the README's "Forking servers" section.
+  FORK_UNSAFE_NETWORK_STACK = RUBY_PLATFORM.include?("darwin")
+
+  class << self
+    # Process-wide defaults. See {Configuration} for every setting.
+    #
+    # @return [ValidEmailChecker::Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Set process-wide defaults.
+    #
+    #   ValidEmailChecker.configure do |config|
+    #     config.from_email = "verify@example.com"
+    #     config.hello_name = "example.com"
+    #     config.timeout = 15
+    #   end
+    #
+    # @yieldparam config [ValidEmailChecker::Configuration]
+    # @return [ValidEmailChecker::Configuration]
+    def configure
+      yield configuration if block_given?
+      configuration.validate!
+    end
+
+    # Restore the default configuration. Mainly useful in tests.
+    #
+    # @return [ValidEmailChecker::Configuration]
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    # Verify one address.
+    #
+    # Performs network I/O and takes seconds. The GVL is released for the
+    # duration, so other Ruby threads keep running.
+    #
+    # @param email [String] the address to check
+    # @param options [Hash] per-call overrides; any {Configuration} setting
+    # @return [ValidEmailChecker::Result]
+    # @raise [ArgumentError] if +email+ is not a non-empty String
+    # @raise [ValidEmailChecker::ConfigurationError] if the options are unusable
+    def check(email, **options)
+      address = coerce_email(email)
+      payload = configuration.merge(options).to_native_payload
+      check_fork_safety!
+
+      Result.from_json(Native.check(address, JSON.generate(payload)))
+    end
+
+    # Verify several addresses, several at a time.
+    #
+    # This is the reason to embed the crate rather than shell out to it: the
+    # whole batch runs on one async runtime under a single GVL release, so
+    # +concurrency+ verifications are in flight at once. Results come back in
+    # the same order as +emails+.
+    #
+    #   results = ValidEmailChecker.check_many(addresses, concurrency: 20)
+    #   results.select(&:safe?).map(&:email)
+    #
+    # Be careful raising +concurrency+ when the addresses share a domain: you
+    # are opening that many SMTP connections to one mail exchanger, which is a
+    # good way to get rate-limited or blacklisted.
+    #
+    # @param emails [Array<String>] the addresses to check
+    # @param options [Hash] per-call overrides; any {Configuration} setting,
+    #   including +concurrency+
+    # @return [Array<ValidEmailChecker::Result>] in the order given
+    def check_many(emails, **options)
+      list = Array(emails).map { |email| coerce_email(email) }
+      return [] if list.empty?
+
+      config = configuration.merge(options)
+      payload = config.to_native_payload
+      concurrency = Integer(config.concurrency)
+
+      if concurrency < 1
+        raise ConfigurationError, "concurrency must be at least 1, got #{config.concurrency.inspect}"
+      end
+
+      check_fork_safety!
+
+      json = Native.check_many(list, JSON.generate(payload), concurrency)
+      JSON.parse(json, symbolize_names: true).map { |data| Result.new(data) }
+    end
+
+    # Parse an address without touching the network.
+    #
+    # Instant and side-effect free, so it is safe to call on user input inline,
+    # including in a request cycle or a model validation.
+    #
+    #   ValidEmailChecker.syntax("someone@gmail.co").suggestion
+    #   # => "someone@gmail.com"
+    #
+    # Note that a suggestion is only offered for an address that parses.
+    # Well-known typo domains such as "gmial.com" are on upstream's blocklist
+    # and come back as simply invalid, with no domain and no suggestion.
+    #
+    # @param email [String]
+    # @return [ValidEmailChecker::Syntax]
+    def syntax(email)
+      Syntax.new(JSON.parse(Native.check_syntax(coerce_email(email)), symbolize_names: true))
+    end
+
+    # Whether an address is well-formed. No network access.
+    #
+    # @param email [String]
+    # @return [Boolean]
+    def syntax_valid?(email)
+      syntax(email).valid?
+    end
+
+    # Which version of the embedded crate this gem was built against.
+    #
+    # @return [Hash] with +:name+, +:version+, +:commit+, +:repository+ and
+    #   +:license+ keys
+    def upstream
+      @upstream ||= JSON.parse(Native.upstream, symbolize_names: true).freeze
+    end
+
+    private
+
+    # Apple's Network.framework is not fork-safe: once a process has resolved
+    # and connected, a child that inherits that state deadlocks inside the
+    # framework on its own first connection, ignoring our timeout entirely.
+    #
+    # We cannot fix the inherited state, so we refuse the call instead of
+    # hanging. The check is limited to platforms where the deadlock is
+    # demonstrable; see {FORK_UNSAFE_NETWORK_STACK}. Set
+    # VALID_EMAIL_CHECKER_ALLOW_FORK=1 to bypass it and take the risk.
+    def check_fork_safety!
+      pid = Process.pid
+
+      if FORK_UNSAFE_NETWORK_STACK &&
+         @verified_in_pid &&
+         @verified_in_pid != pid &&
+         ENV["VALID_EMAIL_CHECKER_ALLOW_FORK"] != "1"
+        raise ForkAfterVerificationError, <<~MSG.strip
+          Refusing to verify in process #{pid}: process #{@verified_in_pid} already
+          verified an address before this one forked from it.
+
+          macOS's Network.framework is not fork-safe, and continuing would deadlock
+          here indefinitely rather than time out.
+
+          Verify only in child processes: load this gem at boot if you like, but do
+          not call check/check_many in a parent that will later fork (for example,
+          during Puma's or Unicorn's preload phase). Set
+          VALID_EMAIL_CHECKER_ALLOW_FORK=1 to bypass this check.
+        MSG
+      end
+
+      @verified_in_pid = pid
+    end
+
+    def coerce_email(email)
+      unless email.is_a?(String)
+        raise ArgumentError, "expected an email address as a String, got #{email.class}"
+      end
+
+      stripped = email.strip
+      raise ArgumentError, "expected an email address, got an empty String" if stripped.empty?
+
+      stripped
+    end
+  end
+end

metadata

@@ -0,0 +1,118 @@
+--- !ruby/object:Gem::Specification
+name: valid_email_checker
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- J. Callahan
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rb_sys
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: |
+  valid_email_checker embeds the Rust crate check-if-email-exists and exposes
+  it to Ruby as a native extension. It validates syntax, looks up MX records,
+  holds an SMTP conversation with the recipient's mail exchanger, and reports
+  disposable, role-based and catch-all addresses -- all in-process, with no
+  HTTP service to run and no mail actually sent.
+email:
+- jcallahan@acm.org
+executables:
+- valid_email_checker
+extensions:
+- ext/valid_email_checker/extconf.rb
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Cargo.lock
+- Cargo.toml
+- LICENSE.txt
+- NOTICE.md
+- README.md
+- exe/valid_email_checker
+- ext/valid_email_checker/Cargo.toml
+- ext/valid_email_checker/extconf.rb
+- ext/valid_email_checker/src/lib.rs
+- ext/valid_email_checker/src/nogvl.rs
+- ext/valid_email_checker/vendor/UPSTREAM.json
+- ext/valid_email_checker/vendor/check-if-email-exists/Cargo.toml
+- ext/valid_email_checker/vendor/check-if-email-exists/LICENSE.AGPL
+- ext/valid_email_checker/vendor/check-if-email-exists/LICENSE.md
+- ext/valid_email_checker/vendor/check-if-email-exists/README.md
+- ext/valid_email_checker/vendor/check-if-email-exists/src/haveibeenpwned.rs
+- ext/valid_email_checker/vendor/check-if-email-exists/src/lib.rs
+- ext/valid_email_checker/vendor/check-if-email-exists/src/misc/b2c.txt
+- ext/valid_email_checker/vendor/check-if-email-exists/src/misc/gravatar.rs
+- ext/valid_email_checker/vendor/check-if-email-exists/src/misc/mod.rs
+- ext/valid_email_checker/vendor/check-if-email-exists/src/misc/roles.txt
+- ext/valid_email_checker/vendor/check-if-email-exists/src/mx/mod.rs
+- ext/valid_email_checker/vendor/check-if-email-exists/src/rules.json
+- ext/valid_email_checker/vendor/check-if-email-exists/src/rules.rs
+- ext/valid_email_checker/vendor/check-if-email-exists/src/smtp/connect.rs
+- ext/valid_email_checker/vendor/check-if-email-exists/src/smtp/error.rs
+- ext/valid_email_checker/vendor/check-if-email-exists/src/smtp/gmail.rs
+- ext/valid_email_checker/vendor/check-if-email-exists/src/smtp/headless.rs
+- ext/valid_email_checker/vendor/check-if-email-exists/src/smtp/http_api.rs
+- ext/valid_email_checker/vendor/check-if-email-exists/src/smtp/mod.rs
+- ext/valid_email_checker/vendor/check-if-email-exists/src/smtp/outlook/headless.rs
+- ext/valid_email_checker/vendor/check-if-email-exists/src/smtp/outlook/microsoft365.rs
+- ext/valid_email_checker/vendor/check-if-email-exists/src/smtp/outlook/mod.rs
+- ext/valid_email_checker/vendor/check-if-email-exists/src/smtp/parser.rs
+- ext/valid_email_checker/vendor/check-if-email-exists/src/smtp/verif_method.rs
+- ext/valid_email_checker/vendor/check-if-email-exists/src/smtp/yahoo/api.rs
+- ext/valid_email_checker/vendor/check-if-email-exists/src/smtp/yahoo/headless.rs
+- ext/valid_email_checker/vendor/check-if-email-exists/src/smtp/yahoo/mod.rs
+- ext/valid_email_checker/vendor/check-if-email-exists/src/syntax/mod.rs
+- ext/valid_email_checker/vendor/check-if-email-exists/src/syntax/normalize.rs
+- ext/valid_email_checker/vendor/check-if-email-exists/src/util/input_output.rs
+- ext/valid_email_checker/vendor/check-if-email-exists/src/util/mod.rs
+- ext/valid_email_checker/vendor/check-if-email-exists/src/util/sentry.rs
+- ext/valid_email_checker/vendor/check-if-email-exists/src/util/ser_with_display.rs
+- lib/valid_email_checker.rb
+- lib/valid_email_checker/configuration.rb
+- lib/valid_email_checker/errors.rb
+- lib/valid_email_checker/result.rb
+- lib/valid_email_checker/syntax.rb
+- lib/valid_email_checker/version.rb
+homepage: https://github.com/johncallahan/valid_email_checker
+licenses:
+- AGPL-3.0-only
+metadata:
+  homepage_uri: https://github.com/johncallahan/valid_email_checker
+  source_code_uri: https://github.com/johncallahan/valid_email_checker
+  changelog_uri: https://github.com/johncallahan/valid_email_checker/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/johncallahan/valid_email_checker/issues
+  upstream_project_uri: https://github.com/reacherhq/check-if-email-exists
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.11
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Check whether an email address really exists, without sending mail.
+test_files: []