nondisposable 0.3.0 → 0.6.0

data/lib/nondisposable/email_validator.rb

@@ -3,16 +3,107 @@
 module ActiveModel
   module Validations
     class NondisposableValidator < EachValidator
+      # Three independent questions about one address, in the order a human
+      # would ask them, and AT MOST ONE error however many of them fire —
+      # stacking "provider is not allowed" on top of "did you mean gmail.com?"
+      # helps nobody:
+      #
+      #   1. Is this a throwaway provider?     (always on — the gem's whole job)
+      #   2. Can we name the address they meant? (config.reject_lookalike_domains,
+      #      or any invalid TLD we can correct — see below)
+      #   3. Is the TLD real, and allowed?     (config.check_tld)
+      #
+      # WHY A NAMEABLE CORRECTION OUTRANKS THE GENERIC TLD ERROR
+      #
+      # `user@gmail.con` fails both 2 and 3. "Doesn't look like a real email
+      # address" is true but useless; "Did you mean user@gmail.com?" is the same
+      # verdict with the fix attached. So whenever we can name a correction we
+      # use that message, whether the TLD was invalid or merely lookalike. The
+      # rule is: a suggestion, if we have one, always phrases the rejection.
+      #
+      # HARD vs CONFIRMABLE — WHICH LOOKALIKES CAN BE WAVED THROUGH
+      #
+      # A lookalike error is only as strong as the evidence behind it:
+      #
+      #   - Invalid TLD (`gmail.con`, `gmailmcom`): HARD. No mail is delivered to
+      #     a TLD that does not exist, so there is nothing to confirm.
+      #   - Reviewed typo (data/known_typo_domains.txt, `gmial.com`): HARD. Someone
+      #     checked; nobody has a mailbox there.
+      #   - Any other lookalike (`gmail.co`, but also `ge.com` → me.com): a GUESS,
+      #     so CONFIRMABLE. The error is added unless the record says the user
+      #     confirmed the address as typed (Nondisposable::ConfirmableEmail). A
+      #     real `ge.com` employee resubmits once and is never locked out.
+      #
+      # `true` and `:confirmable` mean the same thing. Before 0.5.0 `true` refused
+      # every lookalike outright, which measured against the Tranco top 1M would
+      # have refused staff at General Electric, EA and Aon (see CHANGELOG).
       def validate_each(record, attribute, value)
         return if value.blank?
 
         begin
-          domain = value.to_s.split('@').last&.downcase
-          return if domain.nil? # Invalid email format
+          # Without an "@" the whole value is judged as a domain, as it always
+          # has been — someone who typed only `tempmail.com` is still refused.
+          # Unicode form: DisposableDomain canonicalises it, and needs the
+          # unencoded spelling to match rows stored before 0.5.0.
+          domain = value.to_s.include?('@') ? Nondisposable::Domain.from_email(value, unicode: true) : Nondisposable::Domain.unicode(value)
+          return if domain.empty? # Invalid email format
+
+          config = Nondisposable.configuration
+
+          # A domain longer than DNS allows (RFC 1035; RFC 5321 caps it at
+          # 255) cannot receive mail and is in no list, so "not disposable"
+          # would be a lie: refuse it as invalid, whatever else is switched
+          # on. Only for real addresses — a value without "@" is `format:`'s.
+          if value.to_s.include?('@') && Nondisposable::Domain.too_long?(domain)
+            return reject(record, attribute, config.invalid_tld_error_message)
+          end
 
           if Nondisposable::DisposableDomain.disposable?(domain)
-            record.errors.add(attribute, options[:message] || Nondisposable.configuration.error_message)
+            return reject(record, attribute, options[:message] || config.error_message)
+          end
+
+          return unless config.check_tld || config.reject_lookalike_domains
+          # No "@" at all is a malformed value, and this validator has never
+          # judged shape — that is what `format:` is for (see the README). Note
+          # `example@gmailmcom` DOES have one: a domain missing its dot is a real
+          # address at an impossible domain, which is very much our business.
+          return unless value.to_s.include?('@')
+          return unless Nondisposable::Tld.judgeable?(value)
+
+          # nil here means the domain has NO TLD (`example@gmailmcom` — a
+          # production-shaped typo that missed the dot), which fails "must end in a real TLD"
+          # just as surely as `.con` does.
+          tld = Nondisposable::Tld.extract(value)
+          impossible = tld.nil? || !Nondisposable::Tld.valid?(tld)
+          invalid = config.check_tld && impossible
+          blocked = config.check_tld && !invalid && Nondisposable::Tld.blocked?(tld)
+
+          if invalid || config.reject_lookalike_domains
+            suggestion = Nondisposable::Suggestion.for(value)
+            # `@gmial.com` has no local part to build "Did you mean ..." from,
+            # but it is still a reviewed typo: name the domain instead.
+            if suggestion.nil? && config.lookalike_distance.to_i.positive?
+              suggestion = Nondisposable::KnownTypos.correction_for(value)
+            end
+            if suggestion
+              message = config.lookalike_error_message.sub('%{suggestion}', suggestion)
+              # Hard: no confirmation can make an impossible TLD deliverable —
+              # whether or not the host turned check_tld on, `gmail.con` cannot
+              # receive the confirmation email — and a reviewed typo is not a
+              # guess. The error stays a plain message, exactly as before 0.5.0.
+              return reject(record, attribute, message) if impossible || Nondisposable::KnownTypos.include?(value)
+
+              unless Nondisposable::ConfirmableEmail.confirmed?(record, attribute)
+                # Typed, so a form can tell this error apart and offer the
+                # "yes, this is right" checkbox: errors.of_kind?(:email, :lookalike_domain).
+                record.errors.add(attribute, :lookalike_domain, message: message, suggestion: suggestion)
+                return
+              end
+            end
           end
+
+          return reject(record, attribute, config.invalid_tld_error_message) if invalid
+          return reject(record, attribute, config.blocked_tld_error_message) if blocked
         rescue StandardError => e
           if Nondisposable.configuration.on_check_failure == :reject
             Rails.logger.error "[nondisposable] Nondisposable validation error: #{e.message} — rejecting #{attribute} (on_check_failure = :reject)"
@@ -22,6 +113,13 @@ module ActiveModel
           end
         end
       end
+
+      private
+
+      def reject(record, attribute, message)
+        record.errors.add(attribute, message)
+        nil
+      end
     end
 
     module HelperMethods

data/lib/nondisposable/known_typos.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Nondisposable
+  # The only lookalike domains this gem refuses outright.
+  #
+  # "One edit from gmail.com" is a guess, and offline a guess cannot tell
+  # `gmial.com` (a typo) from `ge.com` (General Electric, one edit from me.com).
+  # So a guess may only ever produce a CONFIRMABLE error — the user can say
+  # "yes, that is my address" and carry on. Refusing without that way out needs
+  # something stronger than a guess: a domain somebody looked at and found to be
+  # nothing but a misspelling of a provider — parked or for sale under the
+  # provider's misspelled name, redirecting to the provider, or squatted by a
+  # known typosquatter.
+  #
+  # Those reviewed domains live in data/known_typo_domains.txt, each with the
+  # correction it is a typo OF. The evidence behind every entry is in
+  # test/fixtures/lookalike_corpus.csv, and the test suite fails if an entry
+  # loses it. Nothing generates this list automatically; see the file's header
+  # for the bar an entry has to clear.
+  module KnownTypos
+    LIST_PATH = File.expand_path('../../data/known_typo_domains.txt', __dir__)
+
+    class << self
+      # Is this domain (or address) a reviewed typo?
+      def include?(email_or_domain)
+        !correction_for(email_or_domain).nil?
+      end
+
+      # The provider domain it is a typo of, or nil.
+      def correction_for(email_or_domain)
+        value = email_or_domain.to_s
+        domain = value.include?('@') ? Domain.from_email(value) : Domain.normalize(value)
+        return nil if domain.empty?
+        # A host who added a provider has told us its users are real, which
+        # outranks any review we did without knowing about them.
+        return nil if host_providers.include?(domain)
+
+        all[domain]
+      end
+
+      # typo => correction, frozen. Read once per process.
+      def all
+        @all ||= File.readlines(LIST_PATH, chomp: true).each_with_object({}) do |line, map|
+          value = line.sub(/#.*/, '').strip
+          next if value.empty?
+
+          typo, correction = value.split(/\s+/, 2)
+          map[Domain.normalize(typo)] = Domain.normalize(correction)
+        end.freeze
+      end
+
+      def reload!
+        @all = nil
+        self
+      end
+
+      private
+
+      def host_providers
+        Array(Nondisposable.configuration.additional_email_providers).map { |d| Domain.normalize(d) }
+      end
+    end
+  end
+end

data/lib/nondisposable/precedence.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module Nondisposable
+  # Who wins when two lists disagree about a domain. ONE table, used both when
+  # an address is checked (#decide) and when the stored list is built
+  # (#filter), so the table and the check can never tell different stories:
+  #
+  #   1. config.excluded_domains   (host)  → allowed
+  #   2. data/never_disposable.txt (gem)   → allowed   real providers and ISPs
+  #   3. config.additional_domains (host)  → blocked
+  #   4. data/privacy_relays.txt   (gem)   → config.block_privacy_relays decides
+  #   5. the merged upstream sources       → blocked
+  #
+  # Before 0.6.0, additional_domains was checked FIRST, so a host could not
+  # exclude a domain it had also added. Now the host's exclusion wins: an
+  # allowlist entry is the more deliberate statement, and "a real person
+  # cannot sign up" is the costlier mistake.
+  #
+  # Row 2 outranking row 3 is the deliberate trade-off of this table: a host
+  # can no longer block a real provider (say `mail.ru`) through
+  # additional_domains. That list is for throwaway domains the upstream lists
+  # missed; refusing a whole real provider is a business rule, and belongs in
+  # the host's own validation where it can say so to the user.
+  #
+  # HOW EACH ROW MATCHES
+  #
+  # - excluded_domains: an exact match allows; an excluded parent can never be
+  #   the REASON for a block, but a more specific listed subdomain still blocks
+  #   (unchanged since 0.3.0).
+  # - never_disposable and privacy relays protect their whole namespace
+  #   (`bak.rr.com` is covered by `rr.com`), whatever check_parent_domains says:
+  #   upstream lists really do carry ISP subdomains like that one.
+  # - additional_domains and the stored list follow check_parent_domains.
+  # - No public suffix ever matches anything (Nondisposable::PublicSuffix).
+  module Precedence
+    NEVER_DISPOSABLE_PATH = File.expand_path('../../data/never_disposable.txt', __dir__)
+    PRIVACY_RELAYS_PATH = File.expand_path('../../data/privacy_relays.txt', __dir__)
+    EMAIL_PROVIDERS_PATH = File.expand_path('../../data/email_providers.txt', __dir__)
+
+    # A syntactically possible DNS name, after Domain.normalize: at least two
+    # labels of 1-63 characters, 253 in total, and a final label that is not
+    # all digits (that would be an IP address, not a domain). Underscores are
+    # tolerated inside labels — they are legal in DNS, if not in hostnames, and
+    # rejecting them would only ever make the list shorter, never safer.
+    LABEL = /\A[a-z0-9_](?:[a-z0-9_-]{0,61}[a-z0-9_])?\z/
+
+    class << self
+      # ---- Checking one address ---------------------------------------------
+
+      # The verdict for a normalized domain, given the stored-list candidates
+      # DisposableDomain.match_candidates produced for it:
+      #
+      #   [:allow, nil]          rows 1, 2 or 4 said no
+      #   [:block, nil]          rows 3 or 4 said yes
+      #   [:lookup, candidates]  ask the stored list (row 5) about these
+      def decide(domain, candidates)
+        config = Nondisposable.configuration
+        excluded = configured_set(config.excluded_domains)
+
+        return [:allow, nil] if excluded.include?(domain)
+        return [:allow, nil] if namespace_hit(domain, never_disposable)
+
+        remaining = candidates.reject { |candidate| excluded.include?(candidate) }
+
+        additional = configured_set(config.additional_domains)
+        return [:block, nil] if remaining.any? { |candidate| additional.include?(candidate) }
+
+        # The relay ALLOWANCE covers the whole relay namespace, whatever is
+        # excluded: adding an exclusion must never turn an allowed address into
+        # a refused one (filter drops every relay-namespace row the same way).
+        # Under block_privacy_relays an excluded relay name stops being a
+        # reason to block, like any other exclusion.
+        relay_names = namespace(domain).select { |name| privacy_relays.include?(name) }
+        if relay_names.any?
+          return [:allow, nil] unless config.block_privacy_relays
+          return [:block, nil] if relay_names.any? { |name| !excluded.include?(name) }
+        end
+
+        [:lookup, remaining]
+      end
+
+      # ---- Building the stored list -----------------------------------------
+
+      Result = Struct.new(:kept, :dropped) do
+        # { reason => [domains] }, for logging.
+        def dropped_by_reason
+          dropped.group_by { |_domain, reason| reason }.transform_values { |pairs| pairs.map(&:first).sort }
+        end
+      end
+
+      # Applies the table to a list about to be stored: every upstream domain
+      # is first put in Domain.normalize's canonical form, so every write path
+      # (fetch, seed, bundled fallback) stores exactly the name a lookup asks
+      # for, whoever the caller is. Each then goes through rows 1, 2 and 4 and
+      # the validity checks; the host's additional_domains are added through
+      # row 2 and the validity checks.
+      #
+      # Exclusions are exact here, as they always were: the stored list is not
+      # where parent-level exclusions take effect, #decide is.
+      #
+      # host_policy: false applies only the gem's own rules (validity, public
+      # suffixes, never-disposable, and relays always dropped), ignoring every
+      # host setting. The updater's size guards count that, so their numbers
+      # never depend on the host's configuration.
+      def filter(domains, host_policy: true)
+        config = Nondisposable.configuration
+        excluded = host_policy ? configured_set(config.excluded_domains) : Set.new
+        block_relays = host_policy && config.block_privacy_relays
+        kept = Set.new
+        dropped = []
+
+        domains.each do |raw|
+          domain = Domain.normalize(raw)
+          next if domain.empty?
+
+          reason = invalid_reason(domain) ||
+                   (:excluded if excluded.include?(domain)) ||
+                   (:never_disposable if namespace_hit(domain, never_disposable)) ||
+                   (:privacy_relay if !block_relays && namespace_hit(domain, privacy_relays))
+          reason ? dropped << [domain, reason] : kept << domain
+        end
+
+        Array(host_policy ? config.additional_domains : []).each do |raw|
+          domain = Domain.normalize(raw)
+          next if domain.empty? || excluded.include?(domain)
+
+          reason = (invalid_reason(domain) && :invalid_additional_domain) ||
+                   (:additional_domain_is_never_disposable if namespace_hit(domain, never_disposable))
+          reason ? dropped << [domain, reason] : kept << domain
+        end
+
+        Result.new(kept, dropped)
+      end
+
+      # nil when `domain` (normalized) may be stored, otherwise why not.
+      def invalid_reason(domain)
+        return :invalid unless hostname?(domain)
+        return :public_suffix if PublicSuffix.public_suffix?(domain)
+
+        nil
+      end
+
+      def hostname?(domain)
+        return false if domain.empty? || domain.length > 253
+
+        labels = domain.split('.', -1)
+        labels.size >= 2 &&
+          labels.all? { |label| label.length <= 63 && LABEL.match?(label) } &&
+          !labels.last.match?(/\A\d+\z/)
+      end
+
+      # ---- The bundled lists -------------------------------------------------
+
+      # data/never_disposable.txt + data/email_providers.txt, minus the relays.
+      # Unioned at runtime so a provider added for the typo checks is protected
+      # here too, without anybody remembering to copy it.
+      def never_disposable
+        @never_disposable ||= (read_list(NEVER_DISPOSABLE_PATH) | read_list(EMAIL_PROVIDERS_PATH)).subtract(privacy_relays).freeze
+      end
+
+      def privacy_relays
+        @privacy_relays ||= read_list(PRIVACY_RELAYS_PATH).freeze
+      end
+
+      def reload!
+        @never_disposable = nil
+        @privacy_relays = nil
+        self
+      end
+
+      # The domain and each of its parents down to its registrable domain:
+      # `a.b.rr.com` => ["a.b.rr.com", "b.rr.com", "rr.com"]. Empty for a public
+      # suffix. Never climbs past the registrable domain, so `sch.uk` is not in
+      # the namespace of `school.county.sch.uk`.
+      def namespace(domain)
+        registrable = PublicSuffix.registrable_domain(domain)
+        return [] unless registrable
+
+        labels = domain.split('.')
+        (0..(labels.size - registrable.count('.') - 1)).map { |i| labels.drop(i).join('.') }
+      end
+
+      # The most specific name in `domain`'s namespace that `set` contains.
+      def namespace_hit(domain, set)
+        namespace(domain).find { |name| set.include?(name) }
+      end
+
+      private
+
+      # Host-supplied, so normalized on every read rather than trusted.
+      def configured_set(values)
+        Array(values).each_with_object(Set.new) do |value, set|
+          domain = Domain.normalize(value)
+          set << domain unless domain.empty?
+        end
+      end
+
+      # One domain per line; `#` starts a comment, inline or whole-line.
+      def read_list(path)
+        File.foreach(path, encoding: 'UTF-8').each_with_object(Set.new) do |line, set|
+          domain = Domain.normalize(line.sub(/#.*/, ''))
+          set << domain unless domain.empty?
+        end
+      end
+    end
+  end
+end

data/lib/nondisposable/public_suffix.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module Nondisposable
+  # Is this domain a PUBLIC SUFFIX — a name under which anybody can register
+  # their own domain, like `com`, `co.uk`, `com.br` or `github.io`?
+  #
+  # WHY THE BLOCKLIST NEEDS TO KNOW
+  #
+  # Parent-domain matching blocks `x.tempmail.com` because `tempmail.com` is on
+  # the list. That is exactly right for a registrable domain and exactly wrong
+  # for a public suffix: one bad line reading `com.br` in any upstream list
+  # would refuse every Brazilian company's staff, and nothing in a domain count
+  # or a file size would look unusual. So no public suffix is ever stored, ever
+  # accepted from `additional_domains`, and ever used as a parent-match
+  # candidate. That last one matters on its own: it keeps a row written by an
+  # older version of this gem from doing any damage either.
+  #
+  # WHY A BUNDLED SNAPSHOT AND NOT THE `public_suffix` GEM
+  #
+  # The same reason as Nondisposable::Tld: we need one yes/no answer, offline,
+  # on every signup, with no network and no extra runtime dependency. The list
+  # is the canonical file from https://publicsuffix.org/list/public_suffix_list.dat
+  # (MPL 2.0, redistributed unmodified), ~10,000 rules in ~330 KB, parsed once
+  # into frozen Sets. Both sections are honoured: the ICANN section (`co.uk`)
+  # and the private one (`github.io`, `blogspot.com`), because in both cases the
+  # names below belong to unrelated people. Refresh it with
+  # `rake nondisposable:psl:update` when cutting a release.
+  #
+  # STALENESS
+  #
+  # A suffix added after the snapshot is simply unknown: we would accept a
+  # blocklist entry for it, which is today's behaviour, so a stale snapshot can
+  # only ever be less protective, never lock anybody out.
+  module PublicSuffix
+    LIST_PATH = File.expand_path('../../data/public_suffix_list.dat', __dir__)
+
+    class << self
+      # True when `domain` is itself a public suffix. Single-label names (bare
+      # TLDs, known or not) always are: that is the PSL's implicit `*` rule.
+      # Expects a normalized domain (see Nondisposable::Domain.normalize).
+      def public_suffix?(domain)
+        domain = domain.to_s
+        return false if domain.empty?
+
+        labels = domain.split('.')
+        return true if labels.size == 1
+
+        list = rules
+        return false if list[:exceptions].include?(domain)
+        return true if list[:exact].include?(domain)
+
+        list[:wildcards].include?(labels.drop(1).join('.'))
+      end
+
+      # The registrable domain `domain` belongs to: its longest public suffix
+      # plus one label. `school.county.sch.uk` => itself (`county.sch.uk` is a
+      # suffix via `*.sch.uk`); `x.tempmail.com` => `tempmail.com`. nil when
+      # `domain` is itself a public suffix.
+      #
+      # Everything ABOVE this name belongs to the registry or to unrelated
+      # registrants, so no list entry up there may ever match `domain` — not
+      # even a name like `sch.uk` that is not itself a suffix but sits above a
+      # wildcard one.
+      def registrable_domain(domain)
+        labels = domain.to_s.split('.')
+        return nil if labels.empty? || public_suffix?(domain.to_s)
+
+        # An exception rule prevails (`!city.kawasaki.jp` makes its parent the
+        # suffix); otherwise the longest suffix that is public wins.
+        exceptions = rules[:exceptions]
+        exception = (1..labels.size).find { |n| exceptions.include?(labels.last(n).join('.')) }
+        suffix_size = if exception
+                        exception - 1
+                      else
+                        (1...labels.size).select { |n| public_suffix?(labels.last(n).join('.')) }.max || 1
+                      end
+        labels.last(suffix_size + 1).join('.')
+      end
+
+      # IANA-style provenance for health checks: "2026-10-16_23-32-13_UTC".
+      def version
+        @version ||= begin
+          line = File.foreach(LIST_PATH).first(20).find { |l| l.start_with?('// VERSION:') }
+          line&.delete_prefix('// VERSION:')&.strip
+        rescue StandardError
+          nil
+        end
+      end
+
+      def rule_count
+        list = rules
+        list[:exact].size + list[:wildcards].size + list[:exceptions].size
+      end
+
+      # Reset the memoized rules. Called by the updater after it rewrites the
+      # file, and by tests.
+      def reload!
+        @rules = nil
+        @version = nil
+        self
+      end
+
+      # Parses PSL text into the three rule kinds. Public so the updater can
+      # judge a downloaded body before it replaces the bundled one.
+      #
+      # Rules are stored in their ASCII (punycode) form, because that is the
+      # form Domain.normalize produces. A unicode rule we cannot convert is
+      # kept as-is: it then simply never matches, which errs towards today's
+      # behaviour rather than towards refusing anybody.
+      def parse(text)
+        exact = Set.new
+        wildcards = Set.new
+        exceptions = Set.new
+
+        text.each_line do |line|
+          rule = line.strip
+          next if rule.empty? || rule.start_with?('//')
+
+          rule = rule.split(/\s/, 2).first # the PSL ends a rule at whitespace
+          if rule.start_with?('!')
+            exceptions << ascii(rule.delete_prefix('!'))
+          elsif rule.start_with?('*.')
+            wildcards << ascii(rule.delete_prefix('*.'))
+          else
+            exact << ascii(rule)
+          end
+        end
+
+        { exact: exact.freeze, wildcards: wildcards.freeze, exceptions: exceptions.freeze }.freeze
+      end
+
+      private
+
+      def rules
+        @rules ||= parse(File.read(LIST_PATH, encoding: 'UTF-8'))
+      end
+
+      def ascii(rule)
+        Nondisposable::Domain.normalize(rule)
+      rescue StandardError
+        rule.downcase
+      end
+    end
+  end
+end

data/lib/nondisposable/public_suffix_list_updater.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+
+module Nondisposable
+  # Refreshes the vendored Public Suffix List snapshot.
+  #
+  # ⚠️ A MAINTENANCE task, like TldListUpdater: it rewrites a file inside the
+  # gem, so run it in a checkout before cutting a release:
+  #
+  #   rake nondisposable:psl:update
+  #
+  # Host apps never need it. A stale PSL can only be LESS protective (a suffix
+  # created after the snapshot is not known to be one), never lock anyone out.
+  class PublicSuffixListUpdater
+    # The PSL maintainers ask to be fetched from here and only here.
+    LIST_URL = 'https://publicsuffix.org/list/public_suffix_list.dat'
+
+    OPEN_TIMEOUT = 10
+    READ_TIMEOUT = 10
+
+    # The list holds ~10,000 rules. A body with a fraction of that is an error
+    # page or a truncated download, not the internet shrinking.
+    MINIMUM_PLAUSIBLE_RULE_COUNT = 5_000
+
+    class << self
+      # Returns the number of rules written, or nil if nothing was written.
+      def update(path: Nondisposable::PublicSuffix::LIST_PATH)
+        log :info, "Fetching the Public Suffix List from #{LIST_URL}..."
+
+        response = fetch
+        unless response.is_a?(Net::HTTPSuccess)
+          log :error, "Failed to download the Public Suffix List. HTTP status: #{response.code}. Keeping the existing snapshot."
+          return nil
+        end
+
+        body = response.body.to_s.dup.force_encoding(Encoding::UTF_8)
+        rules = Nondisposable::PublicSuffix.parse(body)
+        count = rules.values.sum(&:size)
+
+        unless body.include?('===BEGIN ICANN DOMAINS===') && count >= MINIMUM_PLAUSIBLE_RULE_COUNT
+          log :error, "Refusing to write a Public Suffix List with only #{count} rules (expected at least #{MINIMUM_PLAUSIBLE_RULE_COUNT} and an ICANN section). Keeping the existing snapshot."
+          return nil
+        end
+
+        # Written whole, then moved into place, so an interrupted run can never
+        # leave half a list behind.
+        tmp = "#{path}.tmp"
+        File.write(tmp, body)
+        File.rename(tmp, path)
+        Nondisposable::PublicSuffix.reload!
+
+        log :info, "Wrote #{count} rules to #{path} (#{Nondisposable::PublicSuffix.version})."
+        count
+      rescue StandardError => e
+        log :error, "Could not update the Public Suffix List: #{e.class}: #{e.message}. Keeping the existing snapshot."
+        nil
+      ensure
+        File.delete(tmp) if tmp && File.exist?(tmp)
+      end
+
+      private
+
+      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