nondisposable 0.2.1 → 0.4.0

data/lib/nondisposable/tld_list_updater.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+
+module Nondisposable
+  # Refreshes the vendored IANA TLD snapshot from the root zone database.
+  #
+  # ⚠️ This is a MAINTENANCE task, not a runtime one — the deliberate opposite of
+  # DomainListUpdater. That one runs in your app, on a schedule, because
+  # disposable domains change every few days and live in your database. This one
+  # rewrites a file inside the gem, which is read-only once the gem is installed.
+  # Run it in a checkout of the gem before cutting a release:
+  #
+  #   rake nondisposable:tlds:update
+  #
+  # If you need a TLD that is newer than your installed gem, do NOT reach for
+  # this. Add it to `config.additional_tlds` and you are unblocked immediately,
+  # with no release and no writable-gem-directory problem:
+  #
+  #   config.additional_tlds = %w[newtld]
+  #
+  # New TLDs are delegated in batches a few times a year, so a snapshot ages
+  # slowly. ICANN's next application round is the first real test of that.
+  class TldListUpdater
+    LIST_URL = 'https://data.iana.org/TLD/tlds-alpha-by-domain.txt'
+
+    OPEN_TIMEOUT = 10
+    READ_TIMEOUT = 10
+
+    # A root zone that suddenly contains a handful of entries means the fetch
+    # went wrong (a captive portal, an error page, a truncated body), not that
+    # ICANN deleted the internet. Refuse to overwrite a good list with junk.
+    MINIMUM_PLAUSIBLE_TLD_COUNT = 1_000
+
+    class << self
+      # Returns the number of TLDs written, or nil if nothing was written.
+      def update(path: Nondisposable::Tld::LIST_PATH)
+        log :info, "Fetching the IANA root zone TLD list from #{LIST_URL}..."
+
+        response = fetch
+        unless response.is_a?(Net::HTTPSuccess)
+          log :error, "Failed to download the TLD list. HTTP status: #{response.code}. Keeping the existing snapshot."
+          return nil
+        end
+
+        body = response.body.to_s
+        count = body.lines.count { |line| meaningful?(line) }
+
+        if count < MINIMUM_PLAUSIBLE_TLD_COUNT
+          log :error, "Refusing to write a TLD list with only #{count} entries (expected at least #{MINIMUM_PLAUSIBLE_TLD_COUNT}). Keeping the existing snapshot."
+          return nil
+        end
+
+        # Written whole, then moved into place, so an interrupted run can never
+        # leave a half-written root zone behind.
+        tmp = "#{path}.tmp"
+        File.write(tmp, body)
+        File.rename(tmp, path)
+        Nondisposable::Tld.reload!
+
+        log :info, "Wrote #{count} TLDs to #{path} (#{Nondisposable::Tld.version})."
+        count
+      rescue StandardError => e
+        log :error, "Could not update the TLD list: #{e.class}: #{e.message}. Keeping the existing snapshot."
+        nil
+      ensure
+        File.delete(tmp) if tmp && File.exist?(tmp)
+      end
+
+      private
+
+      def meaningful?(line)
+        value = line.to_s.strip
+        !value.empty? && !value.start_with?('#')
+      end
+
+      def fetch
+        uri = URI(LIST_URL)
+        Net::HTTP.start(
+          uri.host,
+          uri.port,
+          use_ssl: uri.scheme == 'https',
+          open_timeout: OPEN_TIMEOUT,
+          read_timeout: READ_TIMEOUT
+        ) { |http| http.get(uri.request_uri) }
+      end
+
+      # Usable from a bare `rake` run in a gem checkout, where there is no Rails
+      # logger to talk to.
+      def log(level, message)
+        message = "[nondisposable] #{message}"
+        if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+          Rails.logger.public_send(level, message)
+        else
+          warn message
+        end
+      end
+    end
+  end
+end

data/lib/nondisposable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Nondisposable
-  VERSION = "0.2.1"
+  VERSION = "0.4.0"
 end

data/lib/nondisposable.rb

@@ -2,18 +2,27 @@
 
 require_relative "nondisposable/version"
 require_relative "nondisposable/engine"
+require_relative "nondisposable/tld"
+require_relative "nondisposable/suggestion"
 require_relative "nondisposable/email_validator"
 require_relative "nondisposable/domain_list_updater"
+require_relative "nondisposable/tld_list_updater"
 
 module Nondisposable
   class Error < StandardError; end
 
   class << self
-    attr_accessor :configuration
+    attr_writer :configuration
+
+    # Lazily initialized so the gem works safely even when the host app never
+    # runs an initializer (previously a nil configuration made every check
+    # raise, which the validator surfaced as a validation error on all emails).
+    def configuration
+      @configuration ||= Configuration.new
+    end
   end
 
   def self.configure
-    self.configuration ||= Configuration.new
     yield(configuration)
   end
 
@@ -24,13 +33,124 @@ module Nondisposable
     DisposableDomain.disposable?(domain.downcase)
   end
 
+  # Does this address end in a TLD that actually exists?
+  #
+  # A different question from #disposable?, catching a different kind of bad
+  # address: `user@gmail.con` is not a throwaway, it is a typo that produces an
+  # account nobody can ever reach. Answers true for anything we cannot judge —
+  # no domain, no dot, an IP literal — so it is safe to call on any input; pair
+  # it with a format validation if you also care about shape.
+  def self.valid_tld?(email)
+    return true unless Tld.judgeable?(email)
+
+    tld = Tld.extract(email)
+    return false if tld.nil? # A domain with no TLD can't end in a real one
+
+    Tld.valid?(tld) && !Tld.blocked?(tld)
+  end
+
+  # "someone@gmial.com" => "someone@gmail.com", or nil when we have nothing
+  # useful to say. Never blocks anything by itself — hand it to a user and let
+  # them decide. See Nondisposable::Suggestion for how it decides.
+  def self.suggestion_for(email)
+    Suggestion.for(email)
+  end
+
   class Configuration
+    ON_CHECK_FAILURE_MODES = [:allow, :reject].freeze
+
     attr_accessor :error_message, :additional_domains, :excluded_domains
+    # Whether to also match parent domains: with the default true, an email at
+    # x.tempmail.com is blocked when tempmail.com is on the list (checks up to
+    # DisposableDomain::PARENT_MATCH_DEPTH parent labels, never a bare TLD).
+    attr_accessor :check_parent_domains
+    attr_reader :on_check_failure
+
+    # ---- TLD validity (Nondisposable::Tld) ----------------------------------
+
+    # OFF by default, and it stays off: upgrading a gem must never silently
+    # start rejecting addresses that were fine yesterday. Turn it on to reject
+    # addresses whose TLD is not in the IANA root zone — `user@gmail.con` and
+    # friends, which are typos rather than throwaways but produce an account
+    # nobody can ever reach.
+    attr_accessor :check_tld
+
+    # Your escape hatch from a stale snapshot. A TLD delegated after this gem's
+    # release is unknown to the bundled list; naming it here accepts it
+    # immediately, with no release to wait for. Dots optional: "app" == ".app".
+    attr_accessor :additional_tlds
+
+    # TLDs to refuse even though they are perfectly real. The usual reason is
+    # abuse economics rather than validity — the historically free Freenom set
+    # (%w[tk ml ga cf gq]) is the classic example.
+    attr_accessor :blocked_tlds
+
+    # Allowlist mode: when set, ONLY these TLDs are accepted and every other one
+    # is refused. nil (the default) means "any TLD in the root zone". ⚠️ This is
+    # a blunt instrument — `%w[es]` turns away every customer who happens to use
+    # a .com address. Reach for blocked_tlds first.
+    attr_accessor :allowed_tlds
+
+    # ---- Lookalike domains (Nondisposable::Suggestion) ----------------------
+
+    # Reject addresses one edit away from a well-known provider — `gmail.co`,
+    # `gmial.com`, `hotmial.com` — with a message naming the correction.
+    #
+    # OFF by default and worth leaving off unless you have thought about it: a
+    # suggestion is a guess about intent, and a wrong guess here stops a real
+    # person signing up with their real address. `Nondisposable.suggestion_for`
+    # is always available and blocks nothing, which is the gentler way to use
+    # this: show the hint, let the human decide.
+    attr_accessor :reject_lookalike_domains
+
+    # How many edits still count as "a typo". 1 (the default) is the distance at
+    # which acting on a guess is safe; at 2, genuinely different domains start
+    # colliding with each other. 0 disables suggestions entirely.
+    attr_accessor :lookalike_distance
+
+    # Providers to add to the bundled list — your own domain, a regional
+    # provider we missed. Adding one both makes it a suggestion candidate and,
+    # more importantly, stops its users being told they made a typo.
+    attr_accessor :additional_email_providers
+
+    # ---- Error messages -----------------------------------------------------
+
+    attr_accessor :invalid_tld_error_message, :blocked_tld_error_message
+    # %{suggestion} is replaced with the full corrected address.
+    attr_accessor :lookalike_error_message
 
     def initialize
       @error_message = "provider is not allowed"
       @additional_domains = []
       @excluded_domains = []
+      @on_check_failure = :allow
+      @check_parent_domains = true
+
+      @check_tld = false
+      @additional_tlds = []
+      @blocked_tlds = []
+      @allowed_tlds = nil
+
+      @reject_lookalike_domains = false
+      @lookalike_distance = 1
+      @additional_email_providers = []
+
+      @invalid_tld_error_message = "doesn't look like a real email address"
+      @blocked_tld_error_message = "domain ending is not allowed"
+      @lookalike_error_message = "looks like a typo. Did you mean %{suggestion}?"
+    end
+
+    # What the validator does when the disposable check itself raises
+    # (e.g. the database is unavailable):
+    #   :allow  - let the record through and log an error (availability-first, default)
+    #   :reject - add a validation error, blocking the record (fail closed)
+    def on_check_failure=(mode)
+      mode = mode.to_sym if mode.respond_to?(:to_sym)
+      unless ON_CHECK_FAILURE_MODES.include?(mode)
+        raise ArgumentError, "on_check_failure must be one of #{ON_CHECK_FAILURE_MODES.map(&:inspect).join(', ')} (got #{mode.inspect})"
+      end
+
+      @on_check_failure = mode
     end
   end
 end

data/lib/tasks/nondisposable.rake

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+namespace :nondisposable do
+  namespace :tlds do
+    desc "Refresh the vendored IANA TLD snapshot (maintenance task — run in a gem checkout before a release)"
+    task :update do
+      # Deliberately NOT `require "nondisposable"`: that loads the Engine, which
+      # needs Rails, which a bare `rake` in a gem checkout doesn't have. Nothing
+      # this task touches reads configuration — only `Tld.valid?`/`blocked?` do,
+      # and it calls neither.
+      require_relative "../nondisposable/tld"
+      require_relative "../nondisposable/tld_list_updater"
+
+      before = begin
+        Nondisposable::Tld.all.size
+      rescue StandardError
+        0
+      end
+
+      count = Nondisposable::TldListUpdater.update
+
+      if count.nil?
+        abort "[nondisposable] TLD list unchanged. See the error above."
+      else
+        added = count - before
+        change =
+          if added.positive? then "+#{added}"
+          elsif added.negative? then added.to_s
+          else "no change"
+          end
+        puts "[nondisposable] TLD snapshot now holds #{count} entries (#{change})."
+        puts "[nondisposable] IANA version: #{Nondisposable::Tld.version}"
+        puts "[nondisposable] Commit data/iana_tlds.txt if it changed."
+      end
+    end
+  end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: nondisposable
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.4.0
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-01-17 00:00:00.000000000 Z
+date: 2026-08-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -41,6 +41,10 @@ files:
 - README.md
 - Rakefile
 - app/models/nondisposable/disposable_domain.rb
+- context7.json
+- data/disposable_email_blocklist.conf
+- data/email_providers.txt
+- data/iana_tlds.txt
 - gemfiles/rails_7.2.gemfile
 - gemfiles/rails_8.0.gemfile
 - gemfiles/rails_8.1.gemfile
@@ -52,7 +56,11 @@ files:
 - lib/nondisposable/domain_list_updater.rb
 - lib/nondisposable/email_validator.rb
 - lib/nondisposable/engine.rb
+- lib/nondisposable/suggestion.rb
+- lib/nondisposable/tld.rb
+- lib/nondisposable/tld_list_updater.rb
 - lib/nondisposable/version.rb
+- lib/tasks/nondisposable.rake
 - sig/nondisposable.rbs
 homepage: https://github.com/rameerez/nondisposable
 licenses: