dmarcator 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f09058293dac6f0e31294f06182d69502ee06bc152aa3eb2ef06c07515f4363b
-  data.tar.gz: 6e3aee91c8c8d098c0f066a6b301ef9bc36f42018078769f15e65d695d35ba8a
+  metadata.gz: a1bd93bc4b534e2b9613241e920dd4a71c41e564c92c10ab8abaf6be7294feb8
+  data.tar.gz: fb95401f394f53189a0db431f7d31bc4ffe8c25c87ce87f825f18a99962dadba
 SHA512:
-  metadata.gz: dd47e82f78219d828832c95912a84581ad589efaec940bc25749a0a38b49692805f9afd8030e0f0bd01b2b611dd05a36fec474a8beb9866be340ba9a2e327f39
-  data.tar.gz: 973b12e73708b1540e912063db142ca91e07c5e29cca86e32481222e25334448b8efe754113bfeec6fae591c6411f8a82d796429c7ac36c26e4c22c8c3b714fa
+  metadata.gz: c94318c4ac8a5f7089276f5d6bf91ae90ab8cf576f6367acf418e86adba5fe4bb5e28f7df4a478f8783d134b82bd9390555b3af48c713ca869fd276be4cfe08b
+  data.tar.gz: 6b10b30dfc64acd1cdef7427c4a475d7d9fa90b4c9d387cbc1e2293e8b693e66d3fa4bc23d80d254d92a5a4137ab65b1fe98adfc0e28e573bafc8342274e7995

data/ChangeLog.md

@@ -1,3 +1,25 @@
+### 0.10.0 / 2026-10-29
+
+Breaking changes, taken before 1.0 so the release does not carry them:
+
+* Add `DMARCator::Error` as the base class for every error the library raises. `InvalidRecord`, `InvalidReport` and `ResolutionError` inherit from it, so one `rescue DMARCator::Error` catches all three.
+* `InvalidRecord` no longer inherits from `Parslet::ParseFailed`, removing the parser implementation from the public exception contract. Parse failures still expose the underlying parser error as their `cause`.
+* Remove the deprecated `DMARCator.query` and `DMARCator::Record.query` aliases. Use `DMARCator.dmarc` and `DMARCator::Record.lookup`.
+* Rename `DMARCator::Report::Record` to `DMARCator::Report::Row`, so aggregate rows are not confused with `DMARCator::Record`, the parsed DMARC TXT record.
+
+Migration:
+
+| Before | After |
+|---|---|
+| `DMARCator.query(domain)` | `DMARCator.dmarc(domain)` |
+| `DMARCator::Record.query(domain)` | `DMARCator::Record.lookup(domain)` |
+| `DMARCator::Report::Record` | `DMARCator::Report::Row` |
+| `rescue Parslet::ParseFailed` | `rescue DMARCator::Error` |
+
+### 0.9.0 / 2026-10-29
+
+* Add `DMARCator.txt_records`, which returns the TXT resource records instead of strings, so callers that cache lookups can read each record's `ttl`. `DMARCator.txt` is now defined in terms of it and behaves the same.
+
 ### 0.8.0 / 2026-10-29
 
 * Add `DMARCator.txt`, which returns every TXT record at a name — unfiltered, in response order, with multi-chunk records joined. It accepts service labels such as `_dmarc` and `_domainkey` through a new relaxed `validate_txt_name`, and lets callers detect duplicate DMARC records that `dmarc` deliberately hides.

data/README.md

@@ -104,6 +104,7 @@ The lookup methods are named after what they return:
 
 | Method | Returns | Cost |
 |---|---|---|
+| `DMARCator.txt_records(name)` | `Array<Resolv::DNS::Resource::IN::TXT>` — the records themselves | one lookup |
 | `DMARCator.txt(name)` | `Array<String>` — every TXT record at `name` | one lookup |
 | `DMARCator.dmarc(domain)` | `String` — the DMARC record text, or `nil` | one lookup |
 | `DMARCator::Record.lookup(domain)` | `Record` — parsed | one lookup + parse (~0.4 ms) |
@@ -136,13 +137,24 @@ else :duplicate  # more than one DMARC record breaks enforcement
 end
 ```
 
-All three methods accept an injected resolver, and an injected resolver keeps
-its own configuration (timeouts are only applied to resolvers the library
-builds):
+Use `DMARCator.txt_records` when you need the DNS TTL, for example to cache
+lookups in a database:
+
+```ruby
+records = DMARCator.txt_records("_dmarc.#{domain}")
+records.each do |record|
+  record.strings.join  # the TXT value
+  record.ttl           # seconds the answer may be cached
+end
+```
+
+All of these accept an injected resolver, and an injected resolver keeps its
+own configuration (timeouts are only applied to resolvers the library builds):
 
 ```ruby
 resolver = DMARCator::Resolver::DoH.new(url: "https://dns.example/dns-query")
 DMARCator.txt("_dmarc.example.com", resolver: resolver)
+DMARCator.txt_records("_dmarc.example.com", resolver: resolver)
 DMARCator.dmarc("example.com", resolver: resolver)
 DMARCator::Record.lookup("example.com", resolver: resolver)
 ```
@@ -165,6 +177,22 @@ more than the lookup on a fast resolver); `Resolv::DNS` does not lock per query,
 so use one resolver per thread when parallelising; and DoT/DoH open a new TLS
 connection per lookup, so plaintext is the better choice for bulk work.
 
+### SPF and DKIM
+
+The TXT primitives also cover the other two records a checker needs. There is
+no record-type-specific API, because the semantics belong to the caller:
+
+```ruby
+DMARCator.txt("example.com")                # SPF (RFC 7208)
+DMARCator.txt("s1._domainkey.example.com")  # DKIM (RFC 6376)
+```
+
+Both need the raw list rather than a single value: more than one SPF record is
+a `permerror`, and DKIM keys can be duplicated, rotated or revoked (`p=`). A
+helper returning "the" record would hide exactly those conditions. DKIM is also
+per-selector and selectors cannot be enumerated, so any convenience method would
+have to take a selector and would only build the name above.
+
 ## Strict parsing
 
 By default, unknown tags and tags with invalid values are ignored. Pass

data/lib/dmarcator/exceptions.rb

@@ -1,30 +1,41 @@
 # frozen_string_literal: true
 
-require 'parslet'
-
 module DMARCator
+  #
+  # Base class for every error raised by this library.
+  #
+  # Rescuing this catches parse failures, report failures and DNS lookup
+  # failures alike.
+  #
+  # @since 0.10.0
+  #
+  class Error < StandardError
+  end
+
   #
   # Raised when a DMARC record cannot be parsed.
   #
   # @since 0.2.0
   #
-  class InvalidRecord < Parslet::ParseFailed
+  class InvalidRecord < Error
   end
 
   #
   # Raised when a DMARC XML report cannot be parsed.
   #
-  class InvalidReport < StandardError
+  # @since 0.3.0
+  #
+  class InvalidReport < Error
   end
 
   #
-  # Raised when an encrypted DNS transport fails to return a usable answer.
+  # Raised when a DNS transport fails to return a usable answer.
   #
   # This is deliberately distinct from a missing record: a failed lookup must
   # not be mistaken for a domain without a DMARC policy.
   #
   # @since 0.6.0
   #
-  class ResolutionError < StandardError
+  class ResolutionError < Error
   end
 end

data/lib/dmarcator/query.rb

@@ -171,6 +171,39 @@ module DMARCator
   # @since 0.8.0
   #
   def self.txt(name, resolver: default_resolver)
+    txt_records(name, resolver: resolver).map { |record| record.strings.join }
+  end
+
+  #
+  # Looks up every TXT record at a DNS name, returning the resource records
+  # themselves.
+  #
+  # Like {txt}, but without flattening to strings. The records expose
+  # `strings` and `ttl`, which matters when caching results: use
+  # `record.ttl` to decide how long an answer may be reused.
+  #
+  # @param [String] name
+  #   The DNS name to look up.
+  #
+  # @param [Resolv::DNS, Resolver::DoH, Resolver::DoT] resolver
+  #   The resolver to use. When omitted, one is built from `DMARCATOR_DNS`.
+  #   An injected resolver keeps its own configuration.
+  #
+  # @return [Array<Resolv::DNS::Resource::IN::TXT>]
+  #   The records, or an empty array when the name has none. NXDOMAIN and
+  #   NODATA are indistinguishable here.
+  #
+  # @raise [ResolutionError]
+  #   The lookup failed. A failure is never reported as an empty result.
+  #
+  # @raise [ArgumentError]
+  #   The name is not a syntactically valid DNS name.
+  #
+  # @note Names must be ASCII: pass punycode (A-labels) rather than Unicode.
+  #
+  # @since 0.9.0
+  #
+  def self.txt_records(name, resolver: default_resolver)
     lookup_txt(validate_txt_name(name), resolver: resolver)
   end
 
@@ -204,33 +237,25 @@ module DMARCator
 
     # Per RFC 7489 §6.6.3, use the TXT record beginning with "v=DMARC1".
     # If multiple DMARC records exist, treat the domain as having none.
-    dmarc_records = lookup_txt(name, resolver: resolver).select do |text|
+    dmarc_records = lookup_txt(name, resolver: resolver).map do |record|
+      record.strings.join
+    end.select do |text|
       text.start_with?('v=DMARC1')
     end
 
     dmarc_records.first if dmarc_records.one?
   end
 
-  #
-  # @deprecated Use {dmarc}, which names what it returns. Kept for
-  #   compatibility; it will be removed in a future release.
-  #
-  # @see dmarc
-  #
-  def self.query(domain,resolver=default_resolver)
-    dmarc(domain, resolver: resolver)
-  end
-
   #
   # Looks up the TXT records at an already-validated name.
   #
-  # Shared by {txt} and {dmarc} so both use one transport path.
+  # Shared by {txt}, {txt_records} and {dmarc} so they use one transport path.
   #
   # @param [String] name
   #
   # @param [Resolv::DNS, Resolver::DoH, Resolver::DoT] resolver
   #
-  # @return [Array<String>]
+  # @return [Array<Resolv::DNS::Resource::IN::TXT>]
   #
   # @raise [ResolutionError]
   #
@@ -246,7 +271,7 @@ module DMARCator
       raise ResolutionError, "DNS TXT lookup failed for #{name}: #{error.message}"
     end
 
-    records.map { |record| record.strings.join }
+    records
   end
   private_class_method :lookup_txt
 end

data/lib/dmarcator/record.rb

@@ -285,7 +285,8 @@ module DMARCator
 
       new(attributes)
     rescue Parslet::ParseFailed => error
-      raise InvalidRecord.new(truncate_error_message(error.message), error.cause)
+      # Raising inside the rescue sets this error as the cause automatically.
+      raise InvalidRecord, truncate_error_message(error.message)
     end
 
     # Maximum length of error messages echoed from parsing untrusted input.
@@ -342,16 +343,6 @@ module DMARCator
       end
     end
 
-    #
-    # @deprecated Use {lookup}, which names what it returns. Kept for
-    #   compatibility; it will be removed in a future release.
-    #
-    # @see lookup
-    #
-    def self.query(domain,resolver=DMARCator.default_resolver)
-      lookup(domain, resolver: resolver)
-    end
-
     #
     # Converts the record to a Hash.
     #

data/lib/dmarcator/report/{record.rb → row.rb}

@@ -9,7 +9,10 @@ module DMARCator
     #
     # Represents a single `record` element of a DMARC XML report.
     #
-    class Record
+    # Named `Row` so it is not confused with {DMARCator::Record}, the parsed
+    # DMARC TXT record.
+    #
+    class Row
       include XmlHelper
 
       # Attribute names exposed by this class.

data/lib/dmarcator/report.rb

@@ -8,7 +8,7 @@ require_relative 'xml_helper'
 require_relative 'exceptions'
 require_relative 'report/metadata'
 require_relative 'report/policy'
-require_relative 'report/record'
+require_relative 'report/row'
 
 module DMARCator
   #
@@ -114,11 +114,11 @@ module DMARCator
     #
     # The report records.
     #
-    # @return [Array<Report::Record>]
+    # @return [Array<Report::Row>]
     #
     def records
       @records ||= @node.xpath('feedback/record').map do |node|
-        Record.new(node)
+        Row.new(node)
       end
     end
   end

data/lib/dmarcator/version.rb

@@ -2,5 +2,5 @@
 
 module DMARCator
   # dmarcator version
-  VERSION = '0.8.0'
+  VERSION = '0.10.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dmarcator
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Noah Berman
@@ -78,7 +78,7 @@ files:
 - lib/dmarcator/report/metadata.rb
 - lib/dmarcator/report/policy.rb
 - lib/dmarcator/report/reason.rb
-- lib/dmarcator/report/record.rb
+- lib/dmarcator/report/row.rb
 - lib/dmarcator/resolver.rb
 - lib/dmarcator/resolver/doh.rb
 - lib/dmarcator/resolver/dot.rb