dmarcator 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f09058293dac6f0e31294f06182d69502ee06bc152aa3eb2ef06c07515f4363b
-  data.tar.gz: 6e3aee91c8c8d098c0f066a6b301ef9bc36f42018078769f15e65d695d35ba8a
+  metadata.gz: f4c6e25ca7a0fc2d77204c72ebb01906fce1ac4b537b1e011e505ed2938dda2b
+  data.tar.gz: 36f390d4c0e42c5e938df0345e9d412de2b09aed29da9ca83a424414090b88f1
 SHA512:
-  metadata.gz: dd47e82f78219d828832c95912a84581ad589efaec940bc25749a0a38b49692805f9afd8030e0f0bd01b2b611dd05a36fec474a8beb9866be340ba9a2e327f39
-  data.tar.gz: 973b12e73708b1540e912063db142ca91e07c5e29cca86e32481222e25334448b8efe754113bfeec6fae591c6411f8a82d796429c7ac36c26e4c22c8c3b714fa
+  metadata.gz: 8f3db5da3231a84613e3a938d3e294f01da16df7aee2e633ba321e0002a8278ec28755accb08a1db2e6c72f2d0424cb34ea019b3168b32872503f59dddb6eaa4
+  data.tar.gz: 28d72632daef6199571fd1cd461c112610ebd14bd45a03b48c6b9127f571e82f8431ad35331e4c05d52482b2b5d085bb973a51aa37a888ede498b8b7a85f4eac

data/ChangeLog.md

@@ -1,3 +1,7 @@
+### 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)
 ```

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,7 +237,9 @@ 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
 
@@ -224,13 +259,13 @@ module DMARCator
   #
   # 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 +281,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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dmarcator
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Noah Berman