dmarcator 1.1.0 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d31aa779b69d26db7ac26ef788eca2f9eca47cf5a9fc92e6522df2854e49f1f
-  data.tar.gz: 9100503cce7569587904afa95e680bd9fa0703863873a509475283c7a7f00b0a
+  metadata.gz: c588b9e28df99c70cd55c29c83854064092e2ff74436c9be680afc2b2a77824c
+  data.tar.gz: 3e6692aa15ea2aa28fa451dc847c3cadbd0cb36cdaf237e8bcb6e591206f92d0
 SHA512:
-  metadata.gz: 3fe6fd5ba876573069c9802643e90c79f88ff07840f60abf00addb94564a7c4bb2ce9e6180bc1bbb0960def6fb7d36686815f9938cf8b43136927b040390cfed
-  data.tar.gz: 6238af25582f02123bf5a444522cc42b65947a443dcbcfd5cf251afa1c089a99287011dcc957e07cbc124b9d8511651541dd79ac1d6e47f852c2c827a451ace0
+  metadata.gz: 890fe93593dd8ae6cc2888910070d73606f2700ce3e6548b09cbfcca29f86067788894dbdd23d984a23a7662059514564f955ffdf476656d94110289603b8d4c
+  data.tar.gz: b3357457dbeb21bcd40dee7a412eacc9df9d60b148eae9b0f753c2ca6534d299f4ff6bd7585fcfcf67d4482eabc4f6227ac0878af1d839721de1e2cd7334853f

data/ChangeLog.md

@@ -1,3 +1,17 @@
+### 1.2.1 / 2026-10-30
+
+* Add a record-parser corpus regression net: 143 records (published real-world records plus edge cases) with their accepted outcomes in lenient and strict mode, replayed by the test suite. A parser change that alters how any record parses now fails with a diff. Regenerate with `script/generate_record_corpus.rb`.
+* Report a TCP response body shorter than its declared length as `short DNS response (expected N bytes, got M)`, instead of the opaque `malformed DNS response: limit exceeded`.
+
+No public API changes.
+
+### 1.2.0 / 2026-10-30
+
+* Plaintext lookups now use DNS over TCP (`DMARCator::Resolver::Plain`) instead of `Resolv::DNS`. `Resolv` reads UDP replies into a 512-byte buffer, so a larger answer cannot be decoded, is discarded, and the resulting timeout is swallowed. Any TXT set over 512 bytes — common for SPF and for domains with several DKIM keys — was therefore returned as an empty array, which is indistinguishable from "no records published". TCP has no such limit, and failures raise `ResolutionError`.
+* `DMARCATOR_DNS_TIMEOUT` now applies to plaintext lookups as well (default 5 seconds).
+* `DMARCator::DNS_TIMEOUTS` is no longer used and is deprecated; it will be removed in 2.0.
+* An injected `Resolv::DNS` still works, but carries the same 512-byte UDP limitation. Use `DMARCator::Resolver::Plain`, DoH, or DoT for SPF and DKIM accuracy.
+
 ### 1.1.0 / 2026-10-30
 
 * Replace the Parslet grammar with a hand-written parser in `DMARCator::Internal`. Parsing behaviour is unchanged, verified differentially against the previous parser over 128 real-world and 47 edge-case records in both lenient and strict modes; record parsing is roughly 30x faster (0.84 ms to 0.03 ms per record).

data/README.md

@@ -12,7 +12,7 @@ DMARCator is a Ruby library for parsing and querying [DMARC] records.
 
 [DMARC] policies are published as DNS TXT records at `_dmarc.<domain>`. This
 library parses those records into a structured `DMARCator::Record`, queries them
-directly through Ruby's `Resolv` DNS client, and parses the XML aggregate
+over DNS, and parses the XML aggregate
 reports those policies generate.
 
 ## Installation
@@ -173,9 +173,9 @@ end
 ```
 
 Notes for large scans: `Record.lookup` adds a parse per domain (~0.4 ms, far
-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.
+more than the lookup on a fast resolver); each lookup opens its own TCP
+connection, so keep one resolver per thread when parallelising; and DoT/DoH add
+a TLS handshake per lookup, so plaintext is the better choice for bulk work.
 
 ### SPF and DKIM
 
@@ -205,9 +205,8 @@ DMARCator.configure do |config|
 end
 ```
 
-A resolver object is shared by every thread, and `Resolv::DNS` does not
-serialise concurrent lookups, so threaded applications should configure a
-factory instead:
+A resolver object is shared by every thread, so threaded applications should
+configure a factory instead:
 
 ```ruby
 DMARCator.configure do |config|
@@ -251,8 +250,9 @@ report.records.first.source_ip
 
 ## DNS transport
 
-By default, DMARC lookups use plain DNS through `Resolv`. Encrypted transports
-can be selected with environment variables; no DNS provider is baked in:
+By default, lookups use plain DNS over **TCP** (`DMARCator::Resolver::Plain`).
+Encrypted transports can be selected with environment variables; no DNS provider
+is baked in:
 
 ```sh
 # DNS over HTTPS (RFC 8484)
@@ -271,7 +271,15 @@ export DMARCATOR_DNS_TIMEOUT=5
 
 Certificates are always verified. `DMARCATOR_DOH_IP` pins the address so the
 DoH endpoint does not have to be resolved first; TLS still verifies the URL's
-hostname.
+hostname. `DMARCATOR_DNS_TIMEOUT` applies to every transport, including
+plaintext (default 5 seconds).
+
+Plaintext uses TCP rather than UDP deliberately. `Resolv::DNS` reads UDP replies
+into a 512-byte buffer, so a larger answer cannot be decoded, is discarded, and
+the resulting timeout is swallowed — meaning any TXT set over 512 bytes (common
+for SPF, and for domains with several DKIM keys) came back as an empty result,
+indistinguishable from "no records published". TCP has no such limit, and
+failures raise `DMARCator::ResolutionError`.
 
 Encrypted transports fail closed: a transport failure raises
 `DMARCator::ResolutionError` instead of being reported as a domain without a
@@ -300,9 +308,10 @@ XML helper, the internal resolver plumbing — may change in a minor release.
 * `DMARCator::Record`, `DMARCator::Report` and the parsed value objects are
   read-only after construction and safe to share between threads.
 * The memoized parser and transform are shared, and safe for concurrent use.
-* Resolvers are not necessarily safe for concurrent lookups: `Resolv::DNS` does
-  not serialise queries. Use one resolver per thread, or configure a factory
-  with `DMARCator.configure` so each lookup builds its own.
+* Resolvers are not necessarily safe for concurrent lookups: each lookup opens
+  its own connection, but `Resolv::DNS` (if you inject one) does not serialise
+  queries. Use one resolver per thread, or configure a factory with
+  `DMARCator.configure` so each lookup builds its own.
 * `DMARCator.configure` mutates process-wide state. Call it during boot rather
   than per request.
 
@@ -358,6 +367,21 @@ To run the RSpec tests:
 rake spec
 ```
 
+### Record parser corpus
+
+`spec/support/record_corpus.txt` holds representative records — real-world
+published records and edge cases — and `spec/support/record_corpus.json` the
+outcomes they produced when the corpus was last accepted. The suite replays both
+in lenient and strict mode, so a parser change that alters how any of them parses
+fails with a diff.
+
+If such a change is intentional, regenerate the file and review the JSON diff in
+the commit:
+
+```sh
+ruby -Ilib script/generate_record_corpus.rb
+```
+
 ## Releasing
 
 Every published version must have an annotated tag pointing at the commit that

data/lib/dmarcator/query.rb

@@ -18,8 +18,9 @@ module DMARCator
   #
   # DNS query timeouts in seconds, tried in order.
   #
-  # Applied when the library builds a plaintext resolver. Timeouts on an
-  # injected resolver are left alone.
+  # @deprecated No longer used. Plaintext lookups use a single timeout
+  #   ({Resolver::Plain}), configurable with `DMARCATOR_DNS_TIMEOUT`.
+  #   Removed in 2.0.
   #
   DNS_TIMEOUTS = [2, 4, 8].freeze
 

data/lib/dmarcator/resolver/plain.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'resolv'
+require 'socket'
+
+require_relative '../exceptions'
+require_relative 'encrypted'
+
+module DMARCator
+  module Resolver
+    #
+    # Plain DNS over TCP ([RFC 1035] section 4.2.2).
+    #
+    # TCP rather than UDP on purpose. `Resolv::DNS` reads UDP replies into a
+    # 512-byte buffer, so a larger answer cannot be decoded, is discarded, and
+    # the resulting timeout is swallowed unless `raise_timeout_errors` is set.
+    # Large TXT sets - SPF records, several DKIM keys - therefore came back as
+    # an empty result, which looks exactly like "no records published". TCP has
+    # no such limit, and failures here raise {ResolutionError}.
+    #
+    # [RFC 1035]: https://www.rfc-editor.org/rfc/rfc1035#section-4.2.2
+    #
+    # @since 1.2.0
+    #
+    class Plain < Encrypted
+      # Default DNS port.
+      DEFAULT_PORT = 53
+
+      # Default connect/read timeout in seconds.
+      DEFAULT_TIMEOUT = 5
+
+      # @return [Array<Array(String, Integer)>] the nameservers to try.
+      attr_reader :nameservers
+
+      # @return [Integer] connect/read timeout in seconds.
+      attr_reader :timeout
+
+      #
+      # Builds a resolver from environment variables.
+      #
+      # @param [Hash] env
+      #
+      # @return [Plain]
+      #
+      # @raise [ArgumentError]
+      #   `DMARCATOR_DNS_TIMEOUT` is not an integer.
+      #
+      def self.from_env(env = ENV)
+        new(timeout: timeout_from(env))
+      end
+
+      def self.timeout_from(env)
+        value = env['DMARCATOR_DNS_TIMEOUT']
+
+        value.nil? || value.empty? ? DEFAULT_TIMEOUT : Integer(value, 10)
+      end
+
+      #
+      # The nameservers from the system resolver configuration.
+      #
+      # @return [Array<Array(String, Integer)>]
+      #
+      def self.system_nameservers
+        config = Resolv::DNS::Config.default_config_hash
+
+        if (ports = config[:nameserver_port]) && !ports.empty?
+          return ports.map { |host, port| [host, port || DEFAULT_PORT] }
+        end
+
+        servers = Array(config[:nameserver])
+        servers = ['127.0.0.1'] if servers.empty?
+
+        servers.map { |host| [host, DEFAULT_PORT] }
+      end
+
+      def initialize(nameservers: nil, timeout: DEFAULT_TIMEOUT)
+        @nameservers = (nameservers || self.class.system_nameservers).freeze
+        @timeout = timeout
+
+        raise ArgumentError, 'no nameservers configured' if @nameservers.empty?
+      end
+
+      private
+
+      def exchange(query)
+        wire = query.encode
+        last_error = nil
+
+        @nameservers.each do |host, port|
+          begin
+            return request(host, port, wire)
+          rescue StandardError => error
+            last_error = error
+          end
+        end
+
+        raise ResolutionError,
+              "DNS lookup failed: #{last_error&.message || 'no nameservers'}"
+      end
+
+      def request(host, port, wire)
+        socket = Socket.tcp(host, port, connect_timeout: @timeout)
+        socket.timeout = @timeout if socket.respond_to?(:timeout=)
+
+        socket.write([wire.bytesize].pack('n') + wire)
+
+        header = socket.read(2)
+        raise ResolutionError, 'short DNS response' if header.nil? || header.bytesize < 2
+
+        length = header.unpack1('n')
+        body = socket.read(length)
+
+        if body.nil? || body.bytesize != length
+          raise ResolutionError,
+                "short DNS response (expected #{length} bytes, got #{body&.bytesize || 0})"
+        end
+
+        body
+      ensure
+        socket&.close
+      end
+    end
+  end
+end

data/lib/dmarcator/resolver.rb

@@ -4,6 +4,7 @@ require 'resolv'
 
 require_relative 'exceptions'
 require_relative 'resolver/encrypted'
+require_relative 'resolver/plain'
 require_relative 'resolver/doh'
 require_relative 'resolver/dot'
 
@@ -14,7 +15,7 @@ module DMARCator
   # The transport is chosen with the `DMARCATOR_DNS` environment variable, or
   # explicitly via {.build}:
   #
-  #   DMARCATOR_DNS=plaintext          # default: Resolv::DNS (UDP/TCP)
+  #   DMARCATOR_DNS=plaintext          # default: TCP (Resolver::Plain)
   #   DMARCATOR_DNS=doh                # requires DMARCATOR_DOH_URL
   #   DMARCATOR_DNS=dot                # requires DMARCATOR_DOT_SERVER
   #
@@ -61,9 +62,7 @@ module DMARCator
 
       case name
       when 'plaintext'
-        resolver = Resolv::DNS.new
-        resolver.timeouts = DNS_TIMEOUTS
-        resolver
+        Plain.from_env(env)
       when 'doh'
         DoH.from_env(env)
       when 'dot'

data/lib/dmarcator/version.rb

@@ -2,5 +2,5 @@
 
 module DMARCator
   # dmarcator version
-  VERSION = '1.1.0'
+  VERSION = '1.2.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dmarcator
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.1
 platform: ruby
 authors:
 - Noah Berman
@@ -51,6 +51,7 @@ files:
 - lib/dmarcator/resolver/doh.rb
 - lib/dmarcator/resolver/dot.rb
 - lib/dmarcator/resolver/encrypted.rb
+- lib/dmarcator/resolver/plain.rb
 - lib/dmarcator/uri.rb
 - lib/dmarcator/version.rb
 homepage: https://github.com/bermannoah/dmarcator