mailertogo-spf 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 581850ec95dfe6d56b2fa63dce987667bde0cb512818e8d5f4cd36d7492b68ab
-  data.tar.gz: 4efc0919f45c40599e045fd724b32550611cee5ae142e92f029174808fd93225
+  metadata.gz: 316234e7966e3e895703bbabc960f8cda0b932d7348e654d7afaf1d97c3ee094
+  data.tar.gz: 3a20869ecc92f35b8780672af93e7d38223cbc7e6ae6ca7913b678fae541c37c
 SHA512:
-  metadata.gz: 061357e0bb7fee158f333d4f40acd28f2dbb6306de1347450c7704e022cd1a29925c3f592d655632f5fab580b181a5ede52dc693f7d8d0bf6395a03c55d6735b
-  data.tar.gz: d7244ab5481f550f1213317fc9b4ac8b1d3d8f887bd359c4cdf6102a208fc6a99858c89e0f2aa1810dc6a0db166f50be9df9e9e6508f2f4922ec1c61048094be
+  metadata.gz: d04d30b6ec8059c57d6231ffb786ffb4ce0ad8672b6faad7a29b8f215adbee0c97a3cbeb39078a24ac3988d25d273a6b05b77b02fff51a2be146110ee28927a1
+  data.tar.gz: 58c318462a651629b0cf7d2f11951dcb419486549a947e82fe5f6195c67f6fc694b636e66686bb87aa4b6aff2c13605f94749f3a6c754795a94f5bd15cdeadfb

data/CHANGELOG.md

@@ -4,6 +4,36 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.1] - 2026-08-17
+
+Two `ChainAudit` results could be read as facts when they were really "we did
+not look". Both are corrected in the direction of admitting it.
+
+### Fixed
+
+- `ChainAudit#total` (and `#headroom`) are **`nil` rather than `0`** for a name
+  that publishes no record, or when DNS did not answer. `0` is a legitimate
+  total — `v=spf1 -all` costs exactly that — so a caller that skipped
+  `#published?` could report "this record costs 0 lookups" about a domain with
+  no record. A record that legitimately costs nothing still reports `0`.
+- Duplicate records **at the hostname itself** are reported by the new
+  `#apex_duplicated?` instead of being pushed onto `#duplicated_in_chain`. RFC
+  7208 §4.5 makes them a permerror either way, but the apex is not *in* the
+  chain — it is the record being priced. Folding them together made the same
+  domain audit differently depending on whether the caller supplied `record:` or
+  let the gem resolve the apex, and a caller raising its own duplicate-record
+  defect from the records it resolved would have raised it twice.
+
+### Added
+
+- `ChainAudit#apex_duplicated?` — `true`/`false` when the gem resolved the apex,
+  and `nil` ("cannot say") when the record was supplied or DNS did not answer.
+
+### Changed
+
+- `#duplicated_in_chain` no longer contains the audited hostname. Callers that
+  want that fact ask `#apex_duplicated?`.
+
 ## [0.2.0] - 2026-08-17
 
 Answers a second question about a record: not only "does it authorize me, and

data/README.md

@@ -227,6 +227,22 @@ permerrors the whole evaluation rather than quietly doing nothing:
 ```ruby
 audit.targets_without_spf  # => ["nothing.example.net"]  — include: of a name with no SPF (§5.2)
 audit.duplicated_in_chain  # => ["two.example.net"]      — two v=spf1 records in the chain (§4.5)
+audit.apex_duplicated?     # => false                    — two at the hostname itself (§4.5)
+```
+
+`apex_duplicated?` is deliberately separate from `duplicated_in_chain`: the
+hostname is not *in* the chain, it is the record being priced. It answers `nil`
+— "cannot say" — when you supplied the `record:` yourself, because then we never
+looked at the apex. A caller that resolved the apex already knows, and should
+report from what it saw rather than ask twice.
+
+A record that does not exist cannot be priced, so `total` and `headroom` are
+`nil` rather than `0`. Check `published?` first:
+
+```ruby
+audit = MailerToGo::SPF.chain_audit("no-spf.example.com")
+audit.published?  # => false
+audit.total       # => nil   — not 0; `v=spf1 -all` legitimately costs 0
 ```
 
 Two honesty flags, because a count you could not finish must never read as "it

data/lib/mailertogo/spf/chain_audit.rb

@@ -70,10 +70,12 @@ module MailerToGo
         @resolver = resolver
         @term_class = term_class || Term
         @spent = 0
-        @total = 0
+        @total = nil
         @terms = []
         @targets_without_spf = []
         @duplicated_in_chain = []
+        # nil until we resolve the apex ourselves — "cannot say", not "no".
+        @apex_duplicated = nil
         @resolved = true
         @partial = false
         @capped = false
@@ -100,7 +102,11 @@ module MailerToGo
           seen_all ||= term.all?
         end
 
-        @total = @spent
+        # nil, not 0, when there is nothing to price. 0 is a legitimate total —
+        # `v=spf1 -all` costs exactly that — so using it for "no record" lets a
+        # caller that skipped #published? report "this record costs 0 lookups"
+        # about a domain with no record at all.
+        @total = published? ? @spent : nil
         self
       end
 
@@ -128,10 +134,20 @@ module MailerToGo
       # the number is a floor — for a different reason.
       def capped? = @capped
 
+      # Was there more than one v=spf1 record at the hostname itself? §4.5 makes
+      # that a permerror just as surely as duplicates inside the chain.
+      #
+      # nil means "cannot say" rather than "no": the record was handed to us, so
+      # we never looked at the apex (or DNS did not answer). Only a caller that
+      # let us resolve the apex gets a true/false here — the one that resolved it
+      # already knows, and should report from what it saw rather than ask us.
+      def apex_duplicated? = @apex_duplicated
+
       # How many lookups are still available before the cap, or nil when we
-      # cannot say (a floor cannot answer "how much room is left").
+      # cannot say (a floor cannot answer "how much room is left", and neither
+      # can a record that does not exist).
       def headroom
-        return nil if partial? || capped?
+        return nil if partial? || capped? || !published?
 
         [LIMIT - @total.to_i, 0].max
       end
@@ -150,9 +166,14 @@ module MailerToGo
 
         records = Array(txts).map { |t| Record.normalize_txt(t) }.select { |t| Record.spf_record?(t) }
         # §4.5 — two records at the apex permerror the evaluation just as surely
-        # as two anywhere else in the chain, so they are noted the same way. We
-        # price the first, because there has to be something to read.
-        @duplicated_in_chain << @hostname if records.size > 1
+        # as two anywhere else in the chain. It is reported SEPARATELY from
+        # `duplicated_in_chain` even so, because the apex is not *in* the chain:
+        # it is the record being priced. Folding it in made the same domain audit
+        # differently depending on whether the caller resolved the apex or we
+        # did, and a caller that raises its own duplicate-record defect from the
+        # records it resolved would then raise it twice.
+        @apex_duplicated = records.size > 1
+        # We price the first, because there has to be something to read.
         @record = records.first.to_s
       end
 

data/lib/mailertogo/spf/version.rb

@@ -2,6 +2,6 @@
 
 module MailerToGo
   module SPF
-    VERSION = "0.2.0"
+    VERSION = "0.2.1"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mailertogo-spf
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - MailerToGo