nondisposable 0.6.0 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d0c0a8ad776c00c83c1e8b1e3001c652c5e5b414bb8f79216d3544192843e42
-  data.tar.gz: f2ab66119b84f495ce62d2104ab1c05701441796a969ae793e0fe033c69e6447
+  metadata.gz: 2193d2a242a699cdd8b05767d364d5da7f039f5f2e3203592d0f3222bb8c29db
+  data.tar.gz: bb866074eb28008df4eecd8fab1df646ebbde5eddd6907dfaa43126c3348a315
 SHA512:
-  metadata.gz: 5d2c0d50d9296c92465713fcdf8c97ddfcb3f9b4536ff299b80687f4d0ea12c877a718511bd340d3f1bba897c3e1cc38bdd65ee10c9a3c6f37272cffd3a376cb
-  data.tar.gz: bd6983052fe4a8980a041c99f8aa7a4c41b35c947b5de246d39b10cdbf20c2ad36b2114dd1dad6b481388bcff02a4712977d73bf90c7d132bd0cbd594a5dc245
+  metadata.gz: d88abe6d8b21e332bab766e6a132a1d3e311bba0f067c4a80e5148172249465a58d8053ce3d100d842a3bfebe08dd8910daed05aa8f10d622d9e7a8802ebffa7
+  data.tar.gz: 967dbdbfea2858290d97b150b8e19827314c7031250fd69c274b14a06d4bd9036999ef180a794bc76537c785847babae3a707f69e0837c61b018f159579259b7

data/CHANGELOG.md

@@ -1,3 +1,21 @@
+## [0.6.2] - 2026-10-18
+
+### Fixed
+
+- **A reviewed typo that a blocklist also lists now gets "Did you mean …?", not the disposable message.** The bundled upstream snapshot lists `gmial.com`, `hotmai.com` and `hotmial.com`, three of the entries in `data/known_typo_domains.txt`, and the validator asked the disposable table first, so with `reject_lookalike_domains` on and the table loaded, `ana@gmial.com` was told "provider is not allowed" instead of "Did you mean ana@gmail.com?". The address was refused either way; the message was wrong, and it sent a person who missed a key looking for a problem they don't have. The two **hard** corrections (a reviewed typo, and an impossible TLD with a nameable correction such as `gmail.con`) are now answered before the disposable check, without touching the database: a lookup that raises can neither let `ana@gmial.com` through under `on_check_failure = :allow` nor replace the correction with the generic "cannot check" error under `:reject`. A **guess** still comes after it, and so does the ranker that produces it, so an ordinary listed throwaway never pays for the distance walk: `gotmail.com` and `tmail.com` are both one finger from a provider and listed throwaways, and a confirmable "did you mean" there would only let the user confirm an address that is then refused anyway. **What changes, exactly** (every case below was refused before and is still refused; only the message differs): with `reject_lookalike_domains` on, a reviewed typo gets "Did you mean …?" even when it is listed, whether by an upstream source or by the host's own `additional_domains`, and even over a validator's own `message:` option. With `check_tld` on (alone or not), so does a listed domain whose ending does not exist and for which a correction can be named. Nothing changes with both checks off, at `lookalike_distance = 0`, or for a domain a host put in `additional_email_providers`: the table answers, with the disposable message, as before. The overlap with the blocklist is deliberately **not** filtered out of the stored list: that would let those typos through for every host without the lookalike layer, and for `Nondisposable.disposable?`. Reported by a review of a Rails app integrating the gem.
+- **Reading a "Did you mean …?" error can no longer raise, or rewrite what the user typed.** `%`, `{` and `}` are legal in the local part of an address, and the confirmable error was added as `errors.add(:email, :lookalike_domain, message: …)`, which ActiveModel looks up and I18n-interpolates again on every read. So since 0.5.0, `a%{x}b@gnail.com` made `errors.full_messages` raise `I18n::MissingInterpolationArgument` (a broken signup response), and `a%{value}b@gnail.com` pasted the whole address into the middle of the message. The lookalike errors are now `Nondisposable::LookalikeError`s: an `ActiveModel::Error` whose message is resolved once, when the address is validated, and returned as is from then on. Type and details are unchanged (`errors.of_kind?(:email, :lookalike_domain)`, `errors.details[:email]` => `[{ error: :lookalike_domain, suggestion: … }]`), and `merge!`/`dup` keep the message. The text is computed the way ActiveModel computed it before, once: a per-model `lookalike_domain` translation (`activerecord.errors.models.user.attributes.email.lookalike_domain`) still wins over a configured String, and `%{attribute}` and `%{value}` still interpolate in that String; only what the user typed is no longer read as a pattern.
+
+### Added
+
+- **`config.lookalike_error_message` accepts a Rails error name or a callable**, as well as a String. A Symbol means what it already means for `error_message` and the TLD messages: a short error name (`:email_lookalike`) resolved through ActiveModel's lookup chain (`activerecord.errors.models.user.attributes.email.email_lookalike`, …, `errors.messages.email_lookalike`) in the locale of the request, with `%{suggestion}` (plus `%{attribute}`, `%{value}`) to interpolate. It is resolved once, when the address is validated, so an error read later (in another locale, or by a translation Proc that would raise the second time) shows what was resolved and never "Translation missing". The hard error is added with that name, as `error_message` is; the confirmable one stays typed `:lookalike_domain` with the Symbol as its message, so forms still tell it apart. `:lookalike_domain` itself is refused at boot, since a hard error of that type would offer the confirmation checkbox. A callable is called with the suggestion (`->(suggestion) { … }`) and must return a String. A String works exactly as before, and so does any object answering `#sub`, which until now was the only way to localise this message. `Configuration#lookalike_message(suggestion)` resolves it outside a model (a Symbol under `errors.messages`).
+- **A message that cannot be used never weakens the refusal.** A missing translation, one naming a variable the gem does not pass, a key naming a whole translation group, a `nil` message, a callable that raises, takes no argument or returns something other than a String: each is logged and replaced by the default English message, and the address is still refused. Before, a raise there reached the validator's rescue, where the default `on_check_failure = :allow` accepted the address. A String is now substituted with the block form of `#sub`, so a `\0` or `\&` typed in the local part is printed as typed.
+
+## [0.6.1] - 2026-10-17
+
+### Fixed
+
+- **A populated table is no longer replaced with the bundled list by an update** (an explicit `rollback` still can; see below). In 0.6.0, when a PRIMARY source with a bundled list (the default `disposable-email-domains`) had never been fetched successfully, `DomainListUpdater` put the list bundled with the gem in its place and published it, even over a populated table. **Who is affected:** any host with the `nondisposable_source_snapshots` table whose domain table was populated before the default source had an accepted snapshot of its own. Typically that means an upgrade from 0.4/0.5, with `Sources::DEFAULT` or a multi-source configuration such as `Sources::RECOMMENDED`. If the default source failed on such a host's first update, the table was replaced by the bundled snapshot (plus any other primary that succeeded), and every domain added upstream since the gem's release stopped being blocked until the next successful run. `update` returned false, but the list had already shrunk. Now the bundled stand-in is used **only on an empty table** (a fresh install). With a populated table, publishing is skipped with an error log and the table is kept as it is, until every primary has an accepted snapshot of its own. **The deliberate exception is `DomainListUpdater.rollback`:** withdrawing a poisoned list must always succeed, so there the bundled list still stands in for a primary without a snapshot, whatever the table holds. The emptiness check also bypasses the query cache, so a stale cached answer can never let the bundled list replace rows it never saw. Reported by a codex review in CarHey.
+
 ## [0.6.0] - 2026-10-17
 
 Ships everything listed under 0.5.0 too: 0.5.0 was never released on its own.

data/README.md

@@ -135,7 +135,7 @@ Nondisposable.configure do |config|
 
   config.invalid_tld_error_message = "doesn't look like a real email address"
   config.blocked_tld_error_message = "domain ending is not allowed"
-  config.lookalike_error_message = "looks like a typo. Did you mean %{suggestion}?"
+  config.lookalike_error_message = "looks like a typo. Did you mean %{suggestion}?" # or a Rails error name (:email_lookalike), or a lambda
 end
 ```
 
@@ -252,7 +252,9 @@ config.reject_lookalike_domains = :confirmable # `true` means the same thing
 | any other lookalike the ranker suggests | `gnail.com` | **confirmable**: same message, unless the user confirmed the address |
 | anything else | `ge.com`, `yahoo.com.au` | accepted |
 
-A disposable provider is still refused first, and a blocked TLD is still refused after a confirmation. A host's `additional_email_providers` outranks the known-typo list.
+A disposable provider is refused before any **guess** (a confirmable "did you mean" would only let the user confirm an address that is then refused anyway), and a blocked TLD is still refused after a confirmation. A host's `additional_email_providers` outranks the known-typo list.
+
+The two **hard** corrections — an impossible TLD and a reviewed typo — are answered before the disposable check, without a database query (since 0.6.2). Upstream blocklists carry some reviewed typos (the bundled snapshot lists `gmial.com`, `hotmai.com` and `hotmial.com`), and the address is refused either way; but `ana@gmial.com` is a person who missed a key, not someone hiding behind a temporary inbox, so they get "Did you mean ana@gmail.com?" rather than the disposable message — also over a validator's own `message:`, and when the domain is in your `additional_domains`. Before 0.6.2 these typos got the disposable message whenever the table was loaded.
 
 The known-typo list is short (41 entries) on purpose. An entry needs direct evidence that nobody has a mailbox there — a redirect to the provider or the provider's own DNS (`yaho.com`, `homail.com`), a parking or for-sale network (`gamail.com`, `hotmial.com`), a typosquat redirect or catch-all (`gmial.com`, `gmali.com`), or a registered domain with no MX, A or AAAA record (`gmal.com`). "No MX" alone is not enough: SMTP falls back to the A record. The evidence for every entry is in `test/fixtures/lookalike_corpus.csv`, and the suite fails if an entry loses it.
 
@@ -296,9 +298,31 @@ At most one error is added, however many checks fire — and whenever the gem ca
 | `user@gnail.com` | accepted | same message, confirmable |
 | `user@ge.com` | accepted | accepted |
 | `user@tempmail.com` | "provider is not allowed" | same |
+| `user@gmial.com` (a reviewed typo the blocklist also lists) | "provider is not allowed" | "looks like a typo. Did you mean user@gmail.com?" |
 
 "Doesn't look like a real email address" is true but useless when we know what they meant, so a nameable correction always outranks the generic message.
 
+#### Translating the "Did you mean" message
+
+`lookalike_error_message` takes a String (with `%{suggestion}`), a Rails error name, or anything callable. A Symbol means what it means for `error_message` and the TLD messages: a short error name, looked up when the address is validated through the usual ActiveModel chain (`activerecord.errors.models.user.attributes.email.<name>`, …, `errors.messages.<name>`), so it answers in the current request's locale and can differ per model or attribute:
+
+```ruby
+# config/initializers/nondisposable.rb
+config.lookalike_error_message = :email_lookalike
+```
+
+```yaml
+# config/locales/es.yml
+es:
+  errors:
+    messages:
+      email_lookalike: "parece una errata. ¿Querías decir %{suggestion}?"
+```
+
+`%{suggestion}` is the full corrected address (`ana@gmail.com`), or just the corrected domain when nothing was typed before the `@`; `%{attribute}` and `%{value}` work as in any Rails error message. The hard error is added under that name (`errors.of_kind?(:email, :email_lookalike)`), like `error_message`; the confirmable one stays `:lookalike_domain`, so your checkbox logic doesn't change. That is also why `:lookalike_domain` itself is refused as the name. Unlike an ordinary Rails error, the text is resolved once, when the address is validated, and kept: rendering never looks it up again, so it can't fail later, and whatever the user typed (`%{…}` is legal in an address) is printed as typed.
+
+If the key has no translation in the current locale, Rails' lookup (and I18n's locale fallbacks, if you've turned them on) gets the first try; only when nothing is found does the gem use its default English message, never "Translation missing". The same goes for a translation that names a variable the gem doesn't pass, a key that names a whole group, or a callable that raises: the message falls back and the error is logged, and the address is refused either way, so a broken locale file can never let it through. For anything else, pass a callable that returns a String: `config.lookalike_error_message = ->(suggestion) { I18n.t("my_app.email_typo", suggestion: suggestion) }`. A String works exactly as before, including on the confirmable error: `%{attribute}` and `%{value}` interpolate, and a translation of that model's `lookalike_domain` (`activerecord.errors.models.user.attributes.email.lookalike_domain`) wins over it.
+
 ### Direct Check
 
 You can also check if an email is disposable directly:
@@ -408,7 +432,7 @@ Each source is fetched into its own row in `nondisposable_source_snapshots` (sta
 - it is less than half the source's high-water mark, the largest size ever accepted for it (kept on its newest good snapshot, so neither pruning nor a series of 49% cuts can wear it down; `reset_baseline` is the human override), or more than three times its last good one;
 - it is identical to a snapshot a human rolled back.
 
-Every size is a count of *storable* domains (not junk, not a public suffix, not a known real provider, not a privacy relay), counted the same way whatever your settings, so a payload padded with such lines cannot pass for a full list and changing `block_privacy_relays` or `excluded_domains` never trips a guard. The list is never published empty. A primary that has never been fetched successfully either stands in its bundled list (the default source) or blocks publishing (any other), so a first run can never replace the seed with less than it. Additions and removals are logged per source. A source that lists a known real provider, or a public suffix, is logged as a possible poisoning, and the entry is dropped. Accepting a snapshot, publishing and rolling back all happen under the same lock; downloads happen outside it.
+Every size is a count of *storable* domains (not junk, not a public suffix, not a known real provider, not a privacy relay), counted the same way whatever your settings, so a payload padded with such lines cannot pass for a full list and changing `block_privacy_relays` or `excluded_domains` never trips a guard. The list is never published empty. A primary that has never been fetched successfully blocks publishing, and the current table is kept as it is. Two exceptions let the default source's bundled list stand in for it: an EMPTY table (a fresh install), and an explicit `rollback`, which must always be able to withdraw a poisoned list. So an update can never replace a fresh seed with less than it, nor a table upgraded from 0.4/0.5 (with any source configuration) with an older bundled snapshot. Additions and removals are logged per source. A source that lists a known real provider, or a public suffix, is logged as a possible poisoning, and the entry is dropped. Accepting a snapshot, publishing and rolling back all happen under the same lock; downloads happen outside it.
 
 > [!WARNING]
 > **Two concurrency limits, by design:**

data/lib/generators/nondisposable/templates/nondisposable.rb

@@ -82,4 +82,8 @@ Nondisposable.configure do |config|
   # config.invalid_tld_error_message = "doesn't look like a real email address"
   # config.blocked_tld_error_message = "domain ending is not allowed"
   # config.lookalike_error_message = "looks like a typo. Did you mean %{suggestion}?"
+  # ...or a Rails error name, like the messages above: looked up per request
+  # through ActiveModel's chain, e.g. errors.messages.email_lookalike in your
+  # locale files, with %{suggestion} to interpolate:
+  # config.lookalike_error_message = :email_lookalike
 end

data/lib/nondisposable/domain_list_updater.rb

@@ -303,6 +303,16 @@ module Nondisposable
       def publish!(withdrawn: nil)
         snapshots = {}
         missing_primaries = []
+        # The bundled list may stand in for a never-fetched primary ONLY on an
+        # empty table. A populated table (a host upgrading from 0.4/0.5, whose
+        # rows are newer than this gem's release) is kept as it is until every
+        # primary has an accepted snapshot of its own: replacing it with the
+        # bundled snapshot would silently unblock every domain added upstream
+        # since the release (0.6.1; reported by a CarHey codex review).
+        # A rollback is the deliberate exception: withdrawing a poisoned list
+        # must succeed even when the default source never had a snapshot of
+        # its own, so there the stand-in is used whatever the table holds.
+        table_empty = DisposableDomain.uncached { DisposableDomain.none? }
 
         configured_sources.each do |source|
           snapshot = SourceSnapshot.last_good(source.name)
@@ -310,7 +320,7 @@ module Nondisposable
             snapshots[source] = snapshot.domain_list
           elsif source.name == withdrawn
             log :warn, "#{source.name} has no good snapshot left after the rollback; building the list without it."
-          elsif source.primary? && source.bundled_path
+          elsif source.primary? && source.bundled_path && (table_empty || withdrawn)
             log :warn, "#{source.name} has no good snapshot yet; using the list bundled with the gem in its place."
             snapshots[source] = Source.parse(File.read(source.bundled_path)).domains
           elsif source.primary?
@@ -322,7 +332,8 @@ module Nondisposable
 
         if missing_primaries.any?
           log :error, "Not publishing: primary source(s) #{missing_primaries.join(', ')} have never been fetched successfully. " \
-                      'Keeping the current list (seeding it from the bundled snapshot if it is empty).'
+                      'Keeping the current list unchanged (seeding it from the bundled snapshot only if it is empty) ' \
+                      'until every primary has an accepted snapshot of its own.'
           seed!
           return false
         end
@@ -371,7 +382,9 @@ module Nondisposable
       # ---- Seeding and writing ----------------------------------------------
 
       def seed!
-        return false unless DisposableDomain.none?
+        # Callers hold the publish lock, which already disables the query
+        # cache; asked uncached here as well so no future caller can forget.
+        return false unless DisposableDomain.uncached { DisposableDomain.none? }
 
         log :info, 'Domain table is empty; seeding from the blocklist bundled with the gem...'
         domains = Source.parse(bundled_domains.join("\n")).domains
@@ -465,10 +478,16 @@ module Nondisposable
       # time, and two processes publishing the same snapshots write the same
       # rows. Returns the block's value, or nil when another process held the
       # lock for longer than PUBLISH_LOCK_WAIT (it is publishing the same thing).
+      #
+      # Everything under the lock runs with the query cache OFF: an emptiness
+      # check (`DisposableDomain.none?`) answered from a cache filled before
+      # another process or thread wrote the table would let the bundled list
+      # replace rows it never saw.
       def with_publish_lock(&block)
+        uncached = -> { DisposableDomain.uncached(&block) }
         PROCESS_LOCK.synchronize do
           DisposableDomain.connection_pool.with_connection do |connection|
-            next block.call unless connection.supports_advisory_locks?
+            next uncached.call unless connection.supports_advisory_locks?
 
             acquired = false
             deadline = monotonic + PUBLISH_LOCK_WAIT
@@ -482,7 +501,7 @@ module Nondisposable
             next nil unless acquired
 
             begin
-              block.call
+              uncached.call
             ensure
               connection.release_advisory_lock(PUBLISH_LOCK_ID)
             end

data/lib/nondisposable/email_validator.rb

@@ -1,25 +1,98 @@
 # frozen_string_literal: true
 
+module Nondisposable
+  # A validation error whose message was resolved when it was added, and is
+  # never resolved again.
+  #
+  # An ordinary `errors.add(:email, :some_type, message: "…")` keeps the type
+  # and looks the message up AGAIN every time it is read: the first key of
+  # ActiveModel's chain in whatever locale is current then, and I18n
+  # interpolation over the text. For "Did you mean …?" both are hazards. The
+  # text contains what the user typed, and `%`, `{` and `}` are legal in a
+  # local part, so `a%{x}b@gnail.com` made errors.full_messages raise
+  # I18n::MissingInterpolationArgument (since 0.5.0) and `a%{value}b@…` pasted
+  # the whole address into the middle of it. And a Symbol message we already
+  # checked could resolve differently at render time (another locale, a
+  # translation Proc that raises the second time), outside any fallback.
+  #
+  # So the message is frozen here, while the type and details stay what a
+  # form and an API expect: `errors.of_kind?(:email, :lookalike_domain)`,
+  # `errors.details[:email]` => [{ error: :lookalike_domain, suggestion: … }].
+  # It is in the locale of the request that validated, which is the request
+  # that renders it.
+  class LookalikeError < ActiveModel::Error
+    def initialize(base, attribute, type, resolved_message, **options)
+      super(base, attribute, type, **options)
+      @resolved_message = resolved_message
+    end
+
+    def message
+      @resolved_message
+    end
+  end
+end
+
 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:
+      # Three independent questions about one address, 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:
+      #
+      #   - Is this a throwaway provider?        (always on — the gem's whole job)
+      #   - Can we name the address they meant?  (config.reject_lookalike_domains,
+      #     or any invalid TLD we can correct — see below)
+      #   - Is the TLD real, and allowed?        (config.check_tld)
+      #
+      # The answer is chosen in this order, first match wins:
+      #
+      #   1. A HARD correction: an impossible TLD or a reviewed typo we can name
+      #      the fix for (`gmail.con`, `gmial.com`). "Did you mean …?"
+      #   2. A throwaway provider. "provider is not allowed"
+      #   3. A GUESS (`gnail.com`): the same "Did you mean …?", but confirmable.
+      #   4. An invalid or blocked TLD.
+      #
+      # WHY A HARD CORRECTION OUTRANKS THE THROWAWAY CHECK (since 0.6.2)
+      #
+      # Upstream blocklists carry some of the very typos we reviewed: the
+      # bundled snapshot lists `gmial.com`, `hotmai.com` and `hotmial.com`.
+      # Both verdicts refuse the address, so the order only decides the
+      # MESSAGE, and only one of them is true about the person typing: someone
+      # at `ana@gmial.com` did not pick a temporary inbox, they missed a key
+      # on the way to gmail.com. Being told their provider is a throwaway
+      # sends them looking for a problem they don't have; "Did you mean
+      # ana@gmail.com?" fixes it in one click. A hard correction is certain (no mail reaches
+      # `.con`; somebody checked `gmial.com`), so it is safe to let it phrase a
+      # refusal the blocklist would have made anyway. Until 0.6.2 the throwaway
+      # check ran first, and these typos got the wrong message whenever the
+      # table was loaded.
+      #
+      # It is answered BEFORE the blocklist is even asked, not just phrased
+      # after it: a certain correction needs no database, so a lookup that
+      # raises can neither wave `ana@gmial.com` through (on_check_failure =
+      # :allow) nor bury the correction under the generic "cannot check"
+      # error (:reject). And it is cheap — a hash lookup in the reviewed list,
+      # and the ranker only for an ending that does not exist.
       #
-      #   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)
+      # A guess stays BEHIND the throwaway check. It is only a likelihood, and
+      # the user can answer it: `gotmail.com` and `tmail.com` are both one
+      # finger from a provider AND listed throwaways, so asking "did you mean
+      # hotmail.com?" there would let them tick "yes, this is right" only to
+      # be refused anyway on the next submit. A listed throwaway is the
+      # stronger evidence, and the more useful answer. It is also the
+      # expensive part (a distance walk over every provider), so it runs only
+      # for addresses the blocklist did not already refuse: an ordinary
+      # throwaway never pays for it.
       #
       # 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.
+      # `user@gmail.con` fails both the lookalike and the TLD question. "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 — unless it is a guess about a domain we
+      # KNOW is a throwaway (above).
       #
       # HARD vs CONFIRMABLE — WHICH LOOKALIKES CAN BE WAVED THROUGH
       #
@@ -58,52 +131,34 @@ module ActiveModel
             return reject(record, attribute, config.invalid_tld_error_message)
           end
 
+          spelling = spelling_of(value, config)
+
+          # 1. A certain correction: no database, no ranker for a real ending.
+          # See "why a hard correction outranks the throwaway check" above. A
+          # plain message, not the confirmable :lookalike_domain kind, so a
+          # form never offers "yes, this is right" for it.
+          return add_lookalike_error(record, attribute, config, spelling.correction, confirmable: false) if spelling&.correction
+
+          # 2. A throwaway provider.
           if Nondisposable::DisposableDomain.disposable?(domain)
             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
+          return unless spelling
+
+          # 3. A guess, which the user can confirm. Not when the ending is
+          # impossible: spelling_of already asked the ranker then, and it had
+          # nothing to name.
+          if config.reject_lookalike_domains && !spelling.impossible
             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
+            if suggestion && !Nondisposable::ConfirmableEmail.confirmed?(record, attribute)
+              return add_lookalike_error(record, attribute, config, suggestion, confirmable: true)
             end
           end
 
-          return reject(record, attribute, config.invalid_tld_error_message) if invalid
-          return reject(record, attribute, config.blocked_tld_error_message) if blocked
+          # 4. The TLD itself.
+          return reject(record, attribute, config.invalid_tld_error_message) if spelling.invalid
+          return reject(record, attribute, config.blocked_tld_error_message) if spelling.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)"
@@ -116,6 +171,152 @@ module ActiveModel
 
       private
 
+      # What the TLD and lookalike checks make of an address BEFORE anything
+      # costly runs: no database, and no ranker unless the ending is
+      # impossible.
+      #
+      #   correction  a CERTAIN correction (see #certain_correction), or nil
+      #   impossible  the ending is not a TLD at all (`.con`, or no dot)
+      #   invalid     the TLD fails check_tld
+      #   blocked     the TLD is real, but blocked_tlds/allowed_tlds refuse it
+      Spelling = Struct.new(:correction, :impossible, :invalid, :blocked, keyword_init: true)
+      private_constant :Spelling
+
+      # nil when neither check applies to this value at all.
+      def spelling_of(value, config)
+        return nil 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 nil unless value.to_s.include?('@')
+        return nil 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
+
+        Spelling.new(
+          correction: certain_correction(value, config, impossible),
+          impossible: impossible,
+          invalid: invalid,
+          blocked: config.check_tld && !invalid && Nondisposable::Tld.blocked?(tld)
+        )
+      end
+
+      # A correction no confirmation can override, or nil. Two kinds:
+      #
+      # - An impossible ending with anything the ranker can name (`gmail.con`):
+      #   no mail reaches `.con`, so the guess about WHICH address they meant
+      #   is the only uncertain part, and the refusal is not. Applies whether
+      #   or not the host turned check_tld on — `gmail.con` cannot receive the
+      #   confirmation email either way.
+      # - A reviewed typo (`gmial.com`): somebody checked; nobody has a mailbox
+      #   there. Only with reject_lookalike_domains on, and not at
+      #   lookalike_distance 0, which switches the whole layer off.
+      #
+      # `@gmial.com` has no local part to build "Did you mean ..." from, but
+      # it is still a reviewed typo: name the domain instead.
+      def certain_correction(value, config, impossible)
+        return nil unless config.lookalike_distance.to_i.positive?
+
+        if impossible
+          Nondisposable::Suggestion.for(value) || Nondisposable::KnownTypos.correction_for(value)
+        elsif config.reject_lookalike_domains && Nondisposable::KnownTypos.include?(value)
+          # Suggestion.for asks the reviewed list before the ranker, so this
+          # never pays for a distance walk.
+          Nondisposable::Suggestion.for(value) || Nondisposable::KnownTypos.correction_for(value)
+        end
+      end
+
+      # The "Did you mean …?" error, hard or confirmable.
+      #
+      # The confirmable one is always typed :lookalike_domain (with the
+      # suggestion in its details), so a form can tell it apart and offer the
+      # "yes, this is right" checkbox: errors.of_kind?(:email, :lookalike_domain).
+      # The hard one is a plain message, exactly as before 0.5.0 — or, for a
+      # Symbol, an error of that name, just as error_message and the TLD
+      # messages are added.
+      #
+      # A Symbol resolves through the same ActiveModel chain as every other
+      # Rails error name, and the confirmable error still honours a per-model
+      # `lookalike_domain` translation (#confirmable_message) — but NOW, once,
+      # into a String (see Nondisposable::LookalikeError for why it is never
+      # resolved again). A
+      # translation that is missing, names a variable we don't pass, or is a
+      # whole group (a Hash) is a refusal with a broken message, and we refuse
+      # with the default message instead — never a raise, which
+      # on_check_failure = :allow would turn into an acceptance.
+      def add_lookalike_error(record, attribute, config, suggestion, confirmable:)
+        key = config.lookalike_error_message
+
+        if confirmable
+          add_resolved(record, attribute, :lookalike_domain, confirmable_message(record, attribute, config, suggestion), suggestion)
+        elsif key.is_a?(Symbol)
+          message = resolve_rails_message(record, attribute, config, key, suggestion) || config.default_lookalike_message(suggestion)
+          add_resolved(record, attribute, key, message, suggestion)
+        else
+          # A plain String error, as since 0.5.0: no translation lookup, and
+          # never interpolated when read, so nothing to freeze.
+          record.errors.add(attribute, config.lookalike_message(suggestion))
+        end
+        nil
+      end
+
+      # The confirmable error's text, computed exactly as ActiveModel used to
+      # compute it on every read of `errors.add(attr, :lookalike_domain,
+      # message: …)`, but once:
+      #
+      # - A Symbol replaces the type in Rails' lookup, so it is its own
+      #   chain (#resolve_rails_message).
+      # - Anything else is the default for the FIRST key of the chain,
+      #   activemodel/activerecord.errors.models.<model>.attributes.<attr>.lookalike_domain,
+      #   so an app that translated that key keeps its translation (it did
+      #   until 0.6.1, and must not lose it on upgrade). A String goes in as
+      #   the template it is, with %{suggestion} as a VALUE: I18n never
+      #   rescans a value, so a `%{x}` the user typed is printed, not
+      #   interpolated. A callable's (or a #sub object's) output is already
+      #   final, so its `%` are escaped for the same reason.
+      def confirmable_message(record, attribute, config, suggestion)
+        key = config.lookalike_error_message
+        if key.is_a?(Symbol)
+          return resolve_rails_message(record, attribute, config, key, suggestion) || config.default_lookalike_message(suggestion)
+        end
+
+        template = key.is_a?(String) ? key : config.lookalike_message(suggestion).gsub('%', '%%')
+        text = record.errors.generate_message(attribute, :lookalike_domain, message: template, suggestion: suggestion)
+        raise TypeError, "it resolved to #{text.class}, not a String" unless text.is_a?(String)
+
+        text
+      rescue StandardError => e
+        config.default_lookalike_message(suggestion, e) # logs it
+      end
+
+      # Errors#add would build an ActiveModel::Error that re-resolves its
+      # message on every read; this appends one that does not, the same way
+      # Errors#add appends its own.
+      def add_resolved(record, attribute, type, message, suggestion)
+        record.errors.objects.append(
+          Nondisposable::LookalikeError.new(record, attribute.to_sym, type, message, suggestion: suggestion)
+        )
+      end
+
+      # This Rails error name as a String for this record, in the current
+      # locale (and its I18n fallbacks, when the host has them on), or nil
+      # when it cannot be one.
+      def resolve_rails_message(record, attribute, config, key, suggestion)
+        text = record.errors.generate_message(attribute, key, suggestion: suggestion, raise: true)
+        raise TypeError, "it resolved to #{text.class}, not a String" unless text.is_a?(String)
+
+        text
+      rescue StandardError => e
+        config.default_lookalike_message(suggestion, e) # logs it
+        nil
+      end
+
       def reject(record, attribute, message)
         record.errors.add(attribute, message)
         nil

data/lib/nondisposable/known_typos.rb

@@ -17,6 +17,14 @@ module Nondisposable
   # 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.
+  #
+  # Upstream blocklists list some of these too: the bundled snapshot has
+  # `gmial.com`, `hotmai.com` and `hotmial.com`. That is left alone on purpose: both lists say "refuse it", and dropping the typos from
+  # the stored list would let them through for every host that never switched
+  # the lookalike layer on, and for every Nondisposable.disposable? caller.
+  # What the overlap must not change is the MESSAGE, and the validator settles
+  # that by asking this list before the throwaway check (see
+  # NondisposableValidator), whatever the daily update brings in.
   module KnownTypos
     LIST_PATH = File.expand_path('../../data/known_typo_domains.txt', __dir__)
 

data/lib/nondisposable/version.rb

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

data/lib/nondisposable.rb

@@ -70,6 +70,7 @@ module Nondisposable
   class Configuration
     ON_CHECK_FAILURE_MODES = [:allow, :reject].freeze
     LOOKALIKE_MODES = [false, true, :confirmable].freeze
+    DEFAULT_LOOKALIKE_ERROR_MESSAGE = "looks like a typo. Did you mean %{suggestion}?"
 
     attr_accessor :error_message, :additional_domains, :excluded_domains
     # Whether to also match parent domains: with the default true, an email at
@@ -154,8 +155,22 @@ module Nondisposable
     # ---- 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
+
+    # "Did you mean …?", in one of three forms:
+    #
+    #   "looks like a typo. Did you mean %{suggestion}?"   a String (default)
+    #   :email_lookalike                                   a Rails error name
+    #   ->(suggestion) { "…#{suggestion}…" }               a callable
+    #
+    # %{suggestion} is the full corrected address (or the corrected domain,
+    # for a value with nothing before the "@").
+    #
+    # A Symbol means what it means for error_message and the TLD messages: a
+    # Rails error name, looked up through ActiveModel's chain
+    # (activerecord.errors.models.user.attributes.email.email_lookalike, …,
+    # errors.messages.email_lookalike), with %{suggestion} as well as
+    # %{attribute} and %{value} to interpolate.
+    attr_reader :lookalike_error_message
 
     def initialize
       @error_message = "provider is not allowed"
@@ -179,7 +194,79 @@ module Nondisposable
 
       @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}?"
+      @lookalike_error_message = DEFAULT_LOOKALIKE_ERROR_MESSAGE
+    end
+
+    # `:lookalike_domain` is the TYPE of the confirmable error — the one a form
+    # offers "yes, this is right" for (errors.of_kind?(:email, :lookalike_domain)).
+    # As the name of the hard error too it would put that checkbox next to a
+    # refusal no confirmation can lift, so it fails at boot instead.
+    def lookalike_error_message=(message)
+      if message == :lookalike_domain
+        raise ArgumentError, "lookalike_error_message cannot be :lookalike_domain, the type of the confirmable error: " \
+                             "name the translation anything else (e.g. :email_lookalike)"
+      end
+
+      @lookalike_error_message = message
+    end
+
+    # The lookalike error for this suggestion as a String, resolved NOW, at
+    # validation time, so it answers in the locale of the request being
+    # validated rather than whichever locale the initializer ran in.
+    #
+    # - A Symbol: outside a model there is no ActiveModel chain to walk, so
+    #   this looks up its last link, errors.messages.<name>. (The validator
+    #   adds a Symbol through errors.add instead, so a per-model or
+    #   per-attribute translation wins there.)
+    # - Anything that responds to #call is called with the suggestion.
+    # - Anything else is treated as before 0.6.2: `%{suggestion}` replaced
+    #   with #sub. That keeps a String exactly as it was, and keeps working
+    #   any object a host passed that answers #sub (the only way to localise
+    #   this message until now). A String is substituted with the block
+    #   form, so a `\0` or `\&` typed in the local part is printed, not read
+    #   as a back-reference.
+    #
+    # NEVER RAISES. By the time we phrase this message the address is already
+    # refused; the only open question is the wording. A missing translation,
+    # one naming a variable we don't pass (`%{address}`), a key naming a whole
+    # translation group (a Hash), a nil message, or a callable that raises or
+    # takes no argument would otherwise reach the validator's rescue, where
+    # the default on_check_failure = :allow ACCEPTS the address — a listed
+    # typo let through by a broken locale file. So any failure, or anything
+    # that is not a String, falls back to the default English message, logged
+    # so the host can fix it.
+    def lookalike_message(suggestion)
+      message = lookalike_error_message
+      text =
+        if message.is_a?(Symbol)
+          I18n.t(:"errors.messages.#{message}", suggestion: suggestion, raise: true)
+        elsif message.respond_to?(:call)
+          message.call(suggestion)
+        elsif message.is_a?(String)
+          message.sub('%{suggestion}') { suggestion }
+        else
+          message.sub('%{suggestion}', suggestion) # a host's own object, called exactly as before 0.6.2
+        end
+      raise TypeError, "it resolved to #{text.class}, not a String" unless text.is_a?(String)
+
+      text
+    rescue StandardError => e
+      default_lookalike_message(suggestion, e)
+    end
+
+    # The gem's own English message, for when the host's cannot be used.
+    # Given the error that made it necessary, logs it.
+    def default_lookalike_message(suggestion, error = nil)
+      if error
+        log_message = "[nondisposable] Could not use lookalike_error_message #{lookalike_error_message.inspect} " \
+                      "(#{error.class}: #{error.message}); using the default message, the address is still refused."
+        if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+          Rails.logger.error(log_message)
+        else
+          warn log_message
+        end
+      end
+      DEFAULT_LOOKALIKE_ERROR_MESSAGE.sub('%{suggestion}') { suggestion.to_s }
     end
 
     # What the validator does when the disposable check itself raises

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: nondisposable
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.6.2
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-10-17 00:00:00.000000000 Z
+date: 2026-10-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails