nondisposable 0.3.0 → 0.6.0

data/lib/nondisposable/suggestion.rb

@@ -0,0 +1,336 @@
+# frozen_string_literal: true
+
+module Nondisposable
+  # "Did you mean gmail.com?"
+  #
+  # A TLD check catches the typos that produce a domain ending which cannot
+  # exist — `.con`, `.cpm`, `.ocm`. It structurally cannot catch the far more
+  # common ones, because `.co` (Colombia), `.cm` (Cameroon) and `.om` (Oman) are
+  # all real, delegated TLDs, as are `.se` and `.es`. `user@gmail.co` is a
+  # perfectly well-formed address at a perfectly real TLD, and it is still
+  # almost always a finger that slipped off the `m`.
+  #
+  # So this layer asks a different question: is this domain one keystroke away
+  # from a well-known email provider, while not being one itself?
+  #
+  # HOW IT DECIDES
+  #
+  # Optimal string alignment distance (Damerau-Levenshtein restricted to
+  # adjacent transpositions) against data/email_providers.txt. Transposition
+  # matters more than it looks: `gmial.com` is the single most common Gmail
+  # misspelling, and plain Levenshtein scores it 2 while a human sees one
+  # mistake. Under OSA it scores 1, alongside `gmai.com`, `gmail.co` and
+  # `gmail.con`.
+  #
+  # WHAT ONE EDIT CANNOT TELL APART, AND THE TWO FILTERS THAT FOLLOW
+  #
+  # Replaying "one edit from a provider" against the Tranco top 1M (2026-10-17,
+  # docs/evidence/) flagged 707 domains, and a lot of them are large real
+  # organisations: ge.com, mi.com and se.com are one edit from me.com; ea.com and
+  # aa.com from ya.com; bol.com and uol.com from aol.com; grail.com from
+  # gmail.com. Distance alone cannot see the difference, so two filters decide
+  # what is worth suggesting at all:
+  #
+  #   1. SHORT NAMES ONLY TAKE EDITS AFTER THE NAME. When a provider's name is
+  #      four characters or fewer (me, ya, qq, aol, msn, mail, live, zoho…),
+  #      one edit inside the name lands on somebody else's real domain far more
+  #      often than on a typo. `me.cmo` and `live.cm` are still suggested;
+  #      `ge.com`, `mil.ru` and `love.com` are not.
+  #   2. EVERY EDIT MUST LOOK LIKE A FINGER. A swap (`gmial`), a dropped letter
+  #      (`gmal`, `gmail.co`), a doubled letter (`gmmail`), an extra vowel
+  #      (`gamail`) or a neighbouring key on QWERTY (`gnail`, `gmail.con`) is
+  #      how people mistype. A letter from across the keyboard (`grail`,
+  #      `pmail`, `hive`) is how people spell a different word, and the same
+  #      holds after the name: `.au` is not a slip for `.ar`, nor `.dev` for
+  #      `.de`. Dropping the FIRST letter is not counted either — `cloud.com`
+  #      and `aver.com` are what that spells.
+  #
+  # Measured on the 70% tuning split of test/fixtures/lookalike_corpus.csv
+  # (precision over typo+real rows): distance alone 0.07, filter 1 alone 0.27,
+  # both 0.55, at 79% recall of reviewed typos. The corpus is the Tranco top 1M,
+  # so it is crowded with real popular domains — a signup form sees far more
+  # typos per lookalike than this does. The other 30% is a RETROSPECTIVE
+  # holdout, measured by test/nondisposable/lookalike_corpus_test.rb: the hash
+  # split was chosen before tuning but only committed with the tuned filters,
+  # so it is not a pre-registered holdout, and one early draft was seen
+  # against it.
+  #
+  # These filters only decide what to SUGGEST. They are a likelihood, not proof,
+  # and nothing in this file ever justifies refusing an address on its own —
+  # see Nondisposable::KnownTypos for the only domains the gem refuses outright,
+  # and ActiveModel::Validations::NondisposableValidator for how a suggestion
+  # becomes a confirmable error rather than a wall.
+  #
+  # WHY THE DEFAULT THRESHOLD IS 1, AND WHY THIS IS OFF BY DEFAULT
+  #
+  # One edit is the distance at which a guess is worth showing; at two,
+  # legitimately distinct domains start colliding. The exact match check runs
+  # first and always wins, which is why the provider list has to be generous —
+  # see the header of data/email_providers.txt.
+  #
+  # Suggesting is always available and never blocks:
+  #
+  #   Nondisposable.suggestion_for("someone@gmial.com") # => "someone@gmail.com"
+  #   Nondisposable.suggestion_for("someone@gmail.com") # => nil
+  module Suggestion
+    LIST_PATH = File.expand_path('../../data/email_providers.txt', __dir__)
+
+    # A provider name this short only takes edits after the name. See filter 1
+    # in the header for the evidence.
+    SHORT_NAME_LENGTH = 4
+
+    VOWELS = 'aeiou'
+
+    # Physical neighbours on a QWERTY keyboard, the layout of Spain, Latin
+    # America and the English-speaking world (and the default on phones there).
+    # `ñ` sits right of `l` on the Spanish layout. AZERTY and QWERTZ are left out
+    # on purpose: unioning them makes every key a neighbour of more keys, and
+    # QWERTZ's z/y swap alone would start suggesting zoho.com to zozo.com.
+    KEYBOARD_ROWS = %w[1234567890 qwertyuiop asdfghjklñ zxcvbnm].freeze
+
+    class << self
+      # The full corrected address, or nil when we have nothing useful to say.
+      def for(email)
+        email = email.to_s
+        # Bytes that are not UTF-8 have no keystrokes to correct.
+        email = email.dup.force_encoding(Encoding::UTF_8) unless email.encoding == Encoding::UTF_8
+        return nil unless email.valid_encoding?
+
+        email = email.strip
+        local, _, domain = email.rpartition('@')
+        return nil if local.empty? || domain.empty?
+
+        corrected = correct_domain(domain)
+        return nil if corrected.nil?
+
+        "#{local}@#{corrected}"
+      end
+
+      # The corrected DOMAIN alone, or nil. Split out so a host can offer
+      # "did you mean …?" next to a domain field, not just an email field.
+      def correct_domain(domain)
+        typed = Domain.unicode(domain)
+        return nil if typed.empty?
+        # A real provider is never a typo of another real provider.
+        return nil if providers.include?(Domain.normalize(typed))
+        # 0 switches the whole layer off, reviewed list included.
+        return nil if Nondisposable.configuration.lookalike_distance.to_i < 1
+
+        # A reviewed typo carries its own correction, and it wins over any
+        # guess: the list exists precisely because we checked it.
+        KnownTypos.correction_for(typed) || guess(typed)
+      end
+
+      # The ranker alone: distance plus the two filters, without the reviewed
+      # list. Public so the corpus test can measure the guess on its own —
+      # measuring it with the list in front would mostly measure the list.
+      def guess(domain)
+        typed = Domain.unicode(domain)
+        return nil if typed.empty?
+        return nil if providers.include?(Domain.normalize(typed))
+
+        # Punycode letters are an encoding, not keystrokes: `xn--gmal-xpa.com`
+        # is somebody typing `gmaíl.com`, and its distance to gmail.com in
+        # ASCII is meaningless. We judge the unicode form when we get it and
+        # stay silent on the encoded one.
+        return nil if typed.encoding == Encoding::BINARY # not UTF-8: nothing typed to measure
+        return nil if typed.split('.').any? { |label| label.start_with?('xn--') }
+
+        threshold = Nondisposable.configuration.lookalike_distance.to_i
+        return nil if threshold < 1
+
+        best = nil
+        best_distance = threshold + 1
+
+        targets.each do |candidate|
+          # Cheap rejection before the O(n*m) walk: an edit changes the length
+          # by at most 1 per operation, so anything further apart than the
+          # threshold in length alone cannot be within it.
+          next if (candidate.length - typed.length).abs > threshold
+
+          distance = osa_distance(typed, candidate, best_distance)
+          next if distance >= best_distance
+          next unless plausible?(typed, candidate, distance)
+
+          best = candidate
+          best_distance = distance
+          break if distance == 1 # nothing plausible can beat one edit; stop early
+        end
+
+        best
+      end
+
+      # Every provider, as a frozen Set of canonical (punycode) names: the
+      # bundled list plus anything the host added. This is the EXEMPTION set —
+      # an exact match here is never called a typo. Memoised per configuration
+      # so a host changing config in a test or console is picked up.
+      def providers
+        refresh_cache
+        @providers
+      end
+
+      # The same providers as a human would type them (unicode, not punycode):
+      # what a keystroke is measured against. `bücher.d` is one edit from
+      # `bücher.de` and eleven from `xn--bcher-kva.de`.
+      def targets
+        refresh_cache
+        @targets
+      end
+
+      def reload!
+        @providers = nil
+        @targets = nil
+        @bundled_providers = nil
+        @cache_key = nil
+        self
+      end
+
+      private
+
+      def refresh_cache
+        extra = Array(Nondisposable.configuration.additional_email_providers).map { |d| Domain.unicode(d) }.reject(&:empty?)
+        cache_key = extra.hash
+        return if @cache_key == cache_key && @providers && @targets
+
+        @targets = (bundled_providers + extra).uniq.freeze
+        @providers = @targets.map { |d| Domain.normalize(d) }.to_set.freeze
+        @cache_key = cache_key
+      end
+
+      def bundled_providers
+        @bundled_providers ||= File.readlines(LIST_PATH, chomp: true).filter_map do |line|
+          value = line.strip.downcase
+          value unless value.empty? || value.start_with?('#')
+        end
+      end
+
+      # Does the difference between what was typed and this provider look like
+      # a slip of the finger? The two filters from the header, in code.
+      def plausible?(typed, candidate, distance)
+        name = candidate.split('.').first
+        # The dot itself missed or swapped for a letter (`gmailmcom`,
+        # `gmailcom`): nobody owns a domain shaped like that, and the TLD path
+        # refuses it anyway, so it is always worth naming the correction.
+        return true if typed.count('.') < candidate.count('.') && typed.start_with?(name)
+
+        inside_name = typed.split('.').first != name
+        return false if inside_name && name.length <= SHORT_NAME_LENGTH
+        # The edit model below describes ONE edit. A host that widened
+        # lookalike_distance has opted into coarser guesses; filter 1 still
+        # applies, filter 2 has nothing to say.
+        return true if distance > 1
+
+        finger_slip?(typed, candidate)
+      end
+
+      # One edit, classified — in the name or after it, the same fingers type
+      # both (`gmail.cpm` is as plausible as `gmsil.com`, `yahoo.com.au` as
+      # implausible as `grail.com`). Callers have already established the
+      # distance is exactly 1, so exactly one of these shapes applies.
+      def finger_slip?(typed, candidate)
+        i = 0
+        i += 1 while i < typed.length && i < candidate.length && typed[i] == candidate[i]
+
+        case typed.length - candidate.length
+        when -1
+          # A dropped letter (`gmal`, `hotmal`, `gmail.co`) — but not the
+          # first one: `cloud.com`, `aver.com` and `mail.ch` are what
+          # dropping the first letter of icloud, naver and gmail.ch spells,
+          # and every one of them is somebody's real domain.
+          i.positive?
+        when 1
+          # An extra letter is a slip when it repeats, or sits next to, a
+          # letter it was typed beside (`gmmail`, `gmaiul` — not `mlive`), or
+          # when it is a vowel: spelling by ear adds vowels (`gamail`,
+          # `gimail`) far more often than consonants.
+          extra = typed[i]
+          return true if VOWELS.include?(extra)
+
+          beside = [i.positive? ? typed[i - 1] : nil, typed[i + 1]].compact
+          beside.any? { |near| near == extra || neighbours?(near, extra) }
+        else
+          # A swap (`gmial`) is the one mistake OSA counts as one edit…
+          return true if typed[i + 1] == candidate[i] && typed[i] == candidate[i + 1]
+
+          # …otherwise it is a substitution, which has to be a neighbouring
+          # key — or the same key with an accent (`gmaíl`: on a Spanish
+          # keyboard í is i after a dead key, not a different letter).
+          same_key?(typed[i], candidate[i]) || neighbours?(typed[i], candidate[i])
+        end
+      end
+
+      def same_key?(a, b)
+        a.unicode_normalize(:nfd)[0] == b.unicode_normalize(:nfd)[0]
+      end
+
+      def neighbours?(a, b)
+        keyboard.fetch(a, nil)&.include?(b) || false
+      end
+
+      # key => the keys around it, on a staggered QWERTY: the row's own left and
+      # right, and the two keys above and below that it physically touches.
+      def keyboard
+        @keyboard ||= begin
+          map = Hash.new { |h, k| h[k] = Set.new }
+          KEYBOARD_ROWS.each_with_index do |row, r|
+            row.each_char.with_index do |key, c|
+              touching = [[r, c - 1], [r, c + 1], [r - 1, c], [r - 1, c + 1], [r + 1, c - 1], [r + 1, c]]
+              touching.each do |rr, cc|
+                next if rr.negative? || cc.negative? || rr >= KEYBOARD_ROWS.size
+
+                other = KEYBOARD_ROWS[rr][cc]
+                map[key] << other if other
+              end
+            end
+          end
+          map.default_proc = nil
+          map.freeze
+        end
+      end
+
+      # Optimal string alignment distance, with an early bail-out.
+      #
+      # Two rows instead of a full matrix (we only ever need the previous two),
+      # and if the best cell in a row already exceeds `cutoff` no later row can
+      # come back under it — the distance only grows — so we stop. With ~250
+      # candidates per lookup and a threshold of 1, almost every candidate exits
+      # on the length check above or within the first row or two.
+      # (Empty inputs need no special case: with an empty `a` the loop never
+      # runs and the seeded row already holds the right answer, b.length.)
+      def osa_distance(a, b, cutoff)
+        prev_prev = nil
+        prev = (0..b.length).to_a
+        current = Array.new(b.length + 1)
+
+        a.each_char.with_index do |a_char, i|
+          current[0] = i + 1
+          row_min = current[0]
+
+          b.each_char.with_index do |b_char, j|
+            cost = a_char == b_char ? 0 : 1
+            value = [
+              current[j] + 1,      # insertion
+              prev[j + 1] + 1,     # deletion
+              prev[j] + cost       # substitution
+            ].min
+
+            # Transposition: the one that makes `gmial` a single mistake.
+            if i.positive? && j.positive? && a_char == b[j - 1] && a[i - 1] == b_char
+              value = [value, prev_prev[j - 1] + cost].min
+            end
+
+            current[j + 1] = value
+            row_min = value if value < row_min
+          end
+
+          return cutoff if row_min >= cutoff
+
+          prev_prev = prev
+          prev = current.dup
+        end
+
+        prev[b.length]
+      end
+    end
+  end
+end

data/lib/nondisposable/tld.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module Nondisposable
+  # Is the bit after the last dot a real top-level domain?
+  #
+  # This is a different question from "is this a disposable provider", and it
+  # catches a different kind of bad address: the typo. `user@gmail.con` is not a
+  # throwaway — it is a real person who will never receive their confirmation
+  # email, because `.con` does not exist and never has. Those accounts are born
+  # dead: nobody can reach the user, and the user cannot recover the account.
+  #
+  # WHY A BUNDLED LIST AND NOT A DEPENDENCY
+  #
+  # The list is the IANA root zone database — the authoritative register of every
+  # delegated TLD on the internet, ~1,438 entries in about 9 KB:
+  #
+  #   https://data.iana.org/TLD/tlds-alpha-by-domain.txt
+  #
+  # Every "TLD list" repository on GitHub is a scrape of that file, so we go to
+  # the source. The `tld` gem last shipped in 2014 and its list predates roughly
+  # 1,200 of today's TLDs. `public_suffix` is excellent and alive, but it answers
+  # "is this a valid public suffix" (which includes private entries like
+  # `github.io`) and it would pull the whole Public Suffix List in as a runtime
+  # dependency — the same trade-off DisposableDomain::PARENT_MATCH_DEPTH already
+  # declined, for the same reason.
+  #
+  # WHY IN MEMORY AND NOT IN THE DATABASE
+  #
+  # Disposable domains live in a table because there are 8,000+ of them and they
+  # change every few days. TLDs are 1,438 strings that change a handful of times
+  # a year. A frozen Set costs ~100 KB of process memory, answers in O(1) with no
+  # query per signup, needs no migration, and — unlike a table — cannot be empty
+  # on a fresh install. Refresh it with `rake nondisposable:tlds:update` (or
+  # `Nondisposable::TldListUpdater.update`) when cutting a release.
+  #
+  # STALENESS, AND WHY IT CANNOT LOCK ANYONE OUT
+  #
+  # The failure mode of a stale list is rejecting somebody whose TLD was
+  # delegated after the snapshot. `Nondisposable.configuration.additional_tlds`
+  # is the escape hatch: a host can accept a brand-new TLD immediately, without
+  # waiting for a gem release. And the check is opt-in (`config.check_tld`), so
+  # upgrading the gem never silently starts rejecting anybody.
+  module Tld
+    # The vendored IANA snapshot. Its first line is IANA's own version header,
+    # kept verbatim so the provenance and date of the data ship with it.
+    LIST_PATH = File.expand_path('../../data/iana_tlds.txt', __dir__)
+
+    # The names RFC 6761 and RFC 2606 reserve so they can NEVER be delegated.
+    # They are therefore absent from the root zone, and `check_tld` rejects
+    # them — which is right for a signup form, because no human types
+    # `me@home.test`, and an address there could never receive the confirmation
+    # email anyway.
+    #
+    # It is also, on the day you switch `check_tld` on, why half your test suite
+    # goes red: fixtures live at `user@example.test` for exactly the same reason
+    # the names are reserved. That is a configuration question, not a bug, and
+    # this constant is here so the answer reads like a sentence:
+    #
+    #   config.additional_tlds = Nondisposable::Tld::SPECIAL_USE if Rails.env.local?
+    #
+    # Scope it to your non-production environments. Somewhere in the world
+    # somebody is running an app that really does deliver mail inside `.local`;
+    # if that is you, add it in production too and you are the exception that
+    # proves why this is configuration.
+    SPECIAL_USE = %w[test example invalid localhost local onion].freeze
+
+    class << self
+      # Every TLD IANA has delegated, downcased, as a frozen Set.
+      # Memoized: read once per process, never re-read.
+      def all
+        @all ||= parse(File.readlines(LIST_PATH, chomp: true)).freeze
+      end
+
+      # IANA's own version string for the bundled snapshot, e.g.
+      # "2026082301, Last Updated Mon Aug 24 07:07:01 2026 UTC". Useful in a
+      # health check to see how old your list is.
+      def version
+        @version ||= begin
+          header = File.open(LIST_PATH, &:readline).to_s.strip
+          header.start_with?('#') ? header.sub(/\A#\s*Version\s*/i, '') : nil
+        rescue StandardError
+          nil
+        end
+      end
+
+      # The TLD of an email address or a bare domain, downcased.
+      #
+      # nil means THERE IS NO TLD HERE — which is not the same as "we can't
+      # tell". `example@gmailmcom` (the dot missed entirely) and
+      # `you@localhost` both land here, and under check_tld both are rejected:
+      # a domain with no TLD cannot end in a real one. Ask #judgeable? first if
+      # you need to tell that apart from an address this gem has no opinion on.
+      def extract(email_or_domain)
+        domain = normalize(email_or_domain)
+        return nil if domain.empty?
+
+        labels = domain.split('.')
+        return nil if labels.size < 2
+
+        tld = labels.last
+        tld.empty? ? nil : tld
+      end
+
+      # Is this an address the TLD rules have anything to say about?
+      #
+      # False for the two shapes where "what is the TLD" is the wrong question
+      # rather than a question with a bad answer: an empty domain, and an IP
+      # literal (`user@192.168.0.1`, `user@[10.0.0.1]`). Both are left alone —
+      # deciding whether to accept an IP-literal address is a format policy, and
+      # a validator called `check_tld` has no business making it.
+      def judgeable?(email_or_domain)
+        domain = normalize(email_or_domain)
+        return false if domain.empty?
+        return false if domain.start_with?('[') || domain.match?(/\A[\d.]+\z/)
+
+        true
+      end
+
+      # Is this TLD in the root zone (or in the host's additional_tlds)?
+      #
+      # ⚠️ Non-ASCII TLDs always answer true. IANA lists internationalised TLDs
+      # in punycode (`XN--FIQS8S`), and converting `中国` to that form needs an
+      # IDN library we deliberately do not depend on. Rather than reject every
+      # unicode address, we decline to judge them: a false accept is a nuisance,
+      # a false reject is a locked-out human. Punycode-form addresses, which is
+      # what mail clients actually send, are checked normally.
+      def valid?(tld)
+        tld = tld.to_s.downcase
+        return false if tld.empty?
+        return true unless tld.ascii_only?
+
+        all.include?(tld) || configured(:additional_tlds).include?(tld)
+      end
+
+      # Has the host explicitly blocked this TLD — either by naming it in
+      # `blocked_tlds`, or by naming everything else in `allowed_tlds`?
+      def blocked?(tld)
+        tld = tld.to_s.downcase
+        return false if tld.empty?
+
+        allowed = configured(:allowed_tlds)
+        return true if allowed && !allowed.include?(tld)
+
+        configured(:blocked_tlds).include?(tld)
+      end
+
+      # Reset the memoized list. Called by the updater after it rewrites the
+      # file, and by tests.
+      def reload!
+        @all = nil
+        @version = nil
+        self
+      end
+
+      private
+
+      # The domain half in Nondisposable::Domain's canonical form, minus the
+      # punycode step: trimmed, downcased, no trailing root dot, fullwidth and
+      # ideographic dots read as dots (`foo．tk` ends in `tk`, exactly like
+      # `foo.tk`). Unicode TLDs stay unicode, so #valid? still declines to
+      # judge them.
+      def normalize(email_or_domain)
+        value = email_or_domain.to_s
+        value = value.b unless value.valid_encoding? # unreadable bytes must not raise
+        Nondisposable::Domain.unicode(value.split('@').last.to_s)
+      end
+
+      # Skips IANA's comment header and any blank lines.
+      def parse(lines)
+        lines.each_with_object(Set.new) do |line, set|
+          value = line.to_s.strip.downcase
+          next if value.empty? || value.start_with?('#')
+
+          set << value
+        end
+      end
+
+      # Config lists are host-supplied, so normalise on every read rather than
+      # trusting them to be lowercase, dotless strings. `.tk` and `TK` both work.
+      def configured(key)
+        value = Nondisposable.configuration.public_send(key)
+        return nil if value.nil?
+
+        Set.new(Array(value).map { |tld| tld.to_s.strip.downcase.delete_prefix('.') })
+      end
+    end
+  end
+end

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.3.0"
+  VERSION = "0.6.0"
 end